Agent-Skills.md

Agent Skills: TypeScript Migration

TypeScript version migration guide (5.x to 6 to 7, tsgo native port). Use for TS 6 tsconfig breaking changes, TS 7 Go rewrite rollout, or TS5xxx deprecation codes.

UncategorizedID: secondsky/claude-skills/typescript-migration

Repository

secondsky/claude-skills
secondskyLicense: MIT
19229

Install this agent skill to your local

pnpm dlx add-skill https://github.com/secondsky/claude-skills/tree/HEAD/plugins/typescript-migration/skills/typescript-migration

Skill Files

Browse the full folder contents for typescript-migration.

Download Skill

Loading file tree…

plugins/typescript-migration/skills/typescript-migration/SKILL.md

Skill Metadata

Name
typescript-migration
Description
"TypeScript version migration guide (5.x to 6 to 7, tsgo native port). Use for TS 6 tsconfig breaking changes, TS 7 Go rewrite rollout, or TS5xxx deprecation codes."

TypeScript Migration

Authoritative migration guide for TypeScript 5.x → 6 → 7 (native Go port). Sourced from Microsoft's official announcements.

Status

  • Skill Status: Production Ready
  • Last Updated: 2026-07-09
  • TS 6.0 Released: 2026-03-17 (Final) — last JavaScript-based release
  • TS 7.0 Released: 2026-07-08 — native Go port ("Corsa"), stable
  • Authoritative Sources:
    • TS 7.0 release: https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/
    • TS 6.0 beta: https://devblogs.microsoft.com/typescript/announcing-typescript-6-0-beta/
    • TS 6 → 7 diff tracker: https://github.com/microsoft/typescript-go/blob/main/CHANGES.md
    • ts5to6 tool: https://github.com/andrewbranch/ts5to6

The Golden Rule

NEVER skip TypeScript 6. The only supported paths are 5.x → 6 → 7.

Skipping TS 6 produces a wall of hard errors because TS 7 removes everything TS 6 deprecated. Use "ignoreDeprecations": "6.0" only as a temporary pause inside TS 6; it does NOT work in TS 7.

Quick Triage (1 Minute)

  1. Detect current version — run scripts/detect-ts-version.sh (reads package.json).
  2. Classify the path:
    • 5.x → start with references/migration-playbooks.md § "5.x → 6".
    • 6.x → may go directly to TS 7 (see references/ts7-go-rewrite.md).
    • 5.x wanting TS 7 → must go 5 → 6 → 7 (no shortcuts).
    • Intra-version strict-flag rollout (no version change) → see references/ts-migrating-tool-guide.md for the optional ts-migrating tool.
  3. Audit before changing anything — run scripts/audit-ts7-breakers.sh to detect tooling that breaks under TS 7 (typescript-eslint, ts-morph, ts-node, Vue/Svelte/Astro/MDX/Angular templates, ts-patch, ttypescript, typia, baseUrl, node10, ES5 target).

Project-Type Decision Matrix

| Project type | Recommendation | Why | |---|---|---| | Greenfield, no API-dependent tooling | Adopt TS 7 directly | Full speedup, no blockers | | Existing TS project, no special tooling | 5 → 6 → 7 sequentially | TS 6 surfaces every deprecation as a warning first | | Uses typescript-eslint / ts-morph / API consumers | 5 → 6 → 7 via @typescript/typescript6 side-by-side | TS 7 has no programmatic API until 7.1 | | Vue / Svelte / Astro / MDX (Volar-based) | Stay on TS 6 | Volar needs the programmatic API; not yet supported | | Angular with template type-checking | TS 7 for CLI + TS 6 for editor | Microsoft's official split workaround | | ts-patch / ttypescript / typia / custom AST transformers | Stay on TS 6 until migrated to Oxc/SWC | Transformer API gone in TS 7 |

TS 6 — Top Breaking Changes (Quick View)

| Change | Old default | TS 6 default | Fix | |---|---|---|---| | strict | false | true | Set explicitly or fix errors | | module | CommonJS | esnext | Set commonjs if needed | | target | ES3 | es2025 (floating) | Set explicitly | | moduleResolution | node10 | bundler | Set nodenext for Node targets | | rootDir | inferred | . (tsconfig dir) | Set "rootDir": "./src" | | types | all @types | [] | Set "types": ["node"] | | esModuleInterop | false | true | Remove :false; fix import * as → import | | noUncheckedSideEffectImports | false | true | Fix typos or set false for bundler CSS | | libReplacement | true | false | — | | allowSyntheticDefaultImports | varies | true | — |

Deprecated in 6, HARD ERRORS in 7: target: es5; downlevelIteration; moduleResolution: node | node10 | classic; module: amd | umd | systemjs | none; baseUrl; esModuleInterop: false; allowSyntheticDefaultImports: false; alwaysStrict: false; outFile; module Foo {} keyword; assert { } on imports; /// <reference no-default-lib="true"/>; tsc <file> + tsconfig present (use --ignoreConfig).

For full detail per change including PR citations, examples, and the official ts5to6 codemod usage, load references/ts6-breaking-changes.md.

TS 7 — What Changed (Quick View)

  • Native Go port; the standard typescript npm package IS TS 7 (npm install -D typescript).
  • All TS 6 deprecations become hard errors (see table above).
  • No programmatic Compiler API in 7.0 — TS 7.1 will ship a new one. Affects ts-morph, ts-node, ts-jest, ts-loader, ts-patch, ttypescript, typia, typescript-eslint (use the side-by-side pattern below).
  • preserveConstEnums removed — always emits const enums.
  • stableTypeOrdering now true by default; cannot be turned off.
  • NEW flags: --checkers N (default 4), --builders N, --singleThreaded.
  • NEW breaking change: template literal types preserve Unicode code points (not UTF-16 code units).
  • NEW: JS file handling reworked (Closure-style @enum, @class, ?, postfix ! no longer special).
  • Performance (official, real OSS codebases): 7.7x–11.9x faster builds (up to 16.7x with --checkers 8); 6–26% lower memory.

Full install options, compatibility matrix, performance tables, and known issues in references/ts7-go-rewrite.md.

The Official Side-by-Side Pattern (TS 7 + TS 6 API)

Microsoft's recommended path for projects whose tooling depends on the TS Compiler API. Declare an alias in package.json:

{
  "devDependencies": {
    "@typescript/native": "npm:typescript@^7.0.2",
    "typescript": "npm:@typescript/typescript6@^6.0.2"
  }
}
  • npx tsc runs TS 7 (via the @typescript/native alias).
  • Tools importing typescript (typescript-eslint, ts-morph) transparently get TS 6's API via @typescript/typescript6.
  • A tsc6 executable is also available if a TS 6 invocation is needed directly.
  • Remove this workaround once TS 7.1 ships the new API.

The 4-Step Standard Workflow

  1. Detect — scripts/detect-ts-version.sh reports the installed version.
  2. Audit — scripts/audit-ts7-breakers.sh detects breakers BEFORE any upgrade. scripts/ts6-deprecation-scan.sh extracts TS5xxx codes from tsc output.
  3. Migrate — follow references/migration-playbooks.md for the appropriate path. Run ts5to6 --fixBaseUrl and ts5to6 --fixRootDir if the user explicitly approves (these are official Microsoft-endorsed codemods). All other changes are manual.
  4. Verify — scripts/compare-tsc7-tsc6.sh diffs diagnostic codes between TS 7 tsc and TS 6 tsc6. Match on TSxxxx codes, NOT message text (wording differs between compilers). Delete stale .tsbuildinfo files before the first TS 7 run (incompatible between the JS and Go compilers).

Critical Rules

Always

  • ✅ Migrate through TS 6 — never skip it.
  • ✅ Match on diagnostic codes (TSxxxx), not message wording.
  • ✅ Delete stale .tsbuildinfo before the first TS 7 run.
  • ✅ Cite Microsoft's official blog posts as authoritative; treat third-party tutorials as secondary.
  • ✅ Run audit-ts7-breakers.sh BEFORE any upgrade.

Never

  • ❌ Never install @typescript/native-preview for stable use — it's the legacy nightly package; stable is the standard typescript package.
  • ❌ Never assert the unverified third-party claims listed in references/unverified-claims.md (e.g. "moduleResolution default is node16", "--ts6-migration flag exists", "ES5 target is removed in 6", "--keyofStringsOnly was removed").
  • ❌ Never recommend ts-migrating (the tool) for TS version migration — it only helps tighten compilerOptions within a version.
  • ❌ Never assume VS Code needs a setting key to enable TS 7 — install the official extension; it auto-enables.
  • ❌ Never auto-edit user source via custom scripts — only detection/audit scripts and officially-blessed codemods (ts5to6).

The ts-migrating Tool — Conditional Offer

Offer this tool ONLY when the user wants to enable a stricter compilerOption (e.g. noUncheckedIndexedAccess, strict, erasableSyntaxOnly) on an existing large codebase — NOT for version migration.

Gate conditions (all must hold):

  • Existing, non-greenfield TypeScript project.
  • The goal is enabling a compilerOption incrementally.
  • This is not a tsgo / TS-7 migration.

Warnings:

  • The annotate subcommand rewrites source — run on a clean git tree and review the diff.
  • The IDE plugin has ZERO effect on tsc; wire ts-migrating check into CI for it to matter.
  • // @ts-migrating markers are tech debt needing a cleanup sweep.
  • This is NOT Airbnb's ts-migrate (different tool — JS → TS conversion).

Full install, commands, and gate logic in references/ts-migrating-tool-guide.md.

Common Error Codes

| Code | Meaning | Action | |---|---|---| | TS5011 | rootDir mismatch | Set "rootDir": "./src" | | TS5101 | Option deprecated, stops in TS {ver} | Add "ignoreDeprecations": "6.0" (TS 6 only) or fix | | TS5102 | Option removed | Remove from tsconfig | | TS5107 | Option=value deprecated | Same as TS5101 | | TS5108 | Option=value removed | Remove | | TS5111 | Migration info (baseUrl, node10) | See references/ts6-breaking-changes.md | | TS5112 | tsc file-args + tsconfig present | Use --ignoreConfig |

When to Load References

Load these reference files when the user needs detail beyond the quick-reference above:

| Load This File | When | |---|---| | references/ts6-breaking-changes.md | Migrating to TS 6; need full PR-cited detail on each default change, deprecation, or syntax change | | references/ts7-go-rewrite.md | Adopting TS 7; need install detail, compat matrix, performance tables, known gaps | | references/ecosystem-compatibility.md | Checking whether a specific tool (typescript-eslint, ts-morph, ts-node, vite, webpack, vitest, etc.) works under TS 7 | | references/migration-playbooks.md | Need ordered checklists for 5→6, 6→7, or 5→7-via-6 | | references/ts-migrating-tool-guide.md | User wants to enable a stricter compilerOption incrementally on an existing large codebase | | references/unverified-claims.md | Encountering a claim that contradicts official sources; verify before asserting |

Dependencies

  • Required for migration: typescript (target version), tsconfig.json in the project root.
  • Optional helpers:
    • @andrewbranch/ts5to6 — official codemod for baseUrl / rootDir.
    • @typescript/typescript6 — side-by-side API compat for TS 7.
    • ts-migrating — incremental strict-flag rollout (see guide).

Package Versions (Verified 2026-07-09)

{
  "devDependencies": {
    "typescript": "^7.0.2",
    "@typescript/typescript6": "^6.0.2"
  },
  "optionalHelpers": {
    "@andrewbranch/ts5to6": "latest",
    "ts-migrating": "latest"
  }
}

All facts in this skill are cited to Microsoft's official TypeScript blog (devblogs.microsoft.com/typescript). Third-party tutorial claims that conflict with official sources are catalogued in references/unverified-claims.md and treated as suspect.