Overview
Use this skill to enforce TypeScript 5.9.3 modern defaults and patterns across app and library codebases. Generate modern-only output for new code, and allow legacy retention only as a bounded migration exception.
Load References On Demand
- Read
references/ts-5-9-3-modern-patterns.mdfor archetype selection, tsconfig baselines, and modern typing patterns. - Read
references/ts-5-9-3-legacy-replacements.mdfor old-to-new migrations, banned patterns, and exception handling.
Core Workflow
- Detect the project archetype from
package.json, lockfiles, runtime targets, build tooling, and existingtsconfig*.jsonfiles. - Choose module strategy that matches runtime truth:
- Node runtime:
moduleasnode20ornodenext - Bundler runtime:
moduleResolutionasbundlerwithmoduleasesnext - Library publishing: prefer Node-faithful resolution for compatibility checks
- Type-stripping runtime: enforce erasable TypeScript subset
- Node runtime:
- Apply strict safety baseline and module hygiene defaults from
references/ts-5-9-3-modern-patterns.md. - Implement modern type patterns first (
satisfies,consttype parameters,NoInfer, discriminated unions, explicit boundary typing). - Reject legacy output for new code and apply migration mapping from
references/ts-5-9-3-legacy-replacements.mdwhen touching existing code. - Validate with available typecheck, lint, tests, and build commands in the target project.
Version Contract
- Treat TypeScript
5.9.3stable as the default baseline. - Do not emit TypeScript
6.xor beta-only syntax unless the user explicitly requests it. - Keep recommendations aligned with current TypeScript 5.9 compiler and TSConfig guidance.
Implementation Rules
Project Archetype and Modules
- Decide archetype before changing compiler options.
- Keep module settings runtime-faithful, not preference-driven.
- Keep
moduleDetectionasforceunless a known compatibility constraint requires otherwise.
Import and Export Hygiene
- Keep
verbatimModuleSyntaxenabled. - Use
import typeandexport typefor type-only symbols. - Keep side-effect imports explicit and resolvable.
Type System Patterns
- Prefer
satisfiesto validate shapes without widening literals. - Prefer
consttype parameters in reusable APIs that benefit from literal preservation. - Use built-in
NoInferwhen inference must be constrained. - Model state with discriminated unions when behavior depends on variants.
- Use
unknownat trust boundaries, then narrow with validation.
Compiler Baseline
- Keep
strict: true. - Keep
noUncheckedIndexedAccess: true. - Keep
exactOptionalPropertyTypes: true. - Enable
isolatedModulesin toolchain-mixed repos. - Enable
isolatedDeclarationsfor declaration-heavy library workflows. - Use
noUncheckedSideEffectImportswhen side-effect imports are present.
Tradeoff Handling
- Always propose at least two implementation paths for major TypeScript decisions.
- State concise pros and cons for each option (correctness, compatibility, DX, and migration cost).
- Default to the safest modern option unless user constraints indicate otherwise.
Legacy-Avoidance Guardrails
- Do not generate legacy experimental decorator patterns for new code.
- Do not generate
namespace-centric architecture for new code. - Do not rely on implicit type-only import elision.
- Do not use assertion-heavy shortcuts (
as any, chained assertions) where narrowing is possible. - Do not introduce legacy module ambiguity between ESM and CJS.
Migration-aware exception policy:
- Allow temporary legacy retention only for explicit compatibility constraints in existing code.
- Document exactly what is retained, why it is retained, and the concrete follow-up modernization step.
- Scope each exception narrowly and avoid introducing new dependency on retained legacy behavior.
Output Requirements
When generating or reviewing code, include:
- Environment note: detected archetype, runtime target, and toolchain context.
- Version note: TypeScript baseline and any intentional deviations.
- Decision note: chosen module and compiler strategy with one alternative.
- Tradeoff note: concise pros and cons for chosen path and rejected option.
- Legacy note: removed legacy patterns or bounded exceptions with rationale.
- Validation note: what checks were run and outcomes.
Completion Checklist
- TypeScript 5.9.3 modern baseline is enforced.
- Project archetype was detected before config or code changes.
- Module strategy matches runtime behavior.
- Strict safety flags are enabled intentionally.
- New code avoids legacy patterns.
- Any retained legacy pattern is documented with a migration path.
- Typecheck and relevant project validations were executed when available.