Typescript Migration

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

TS 6 — Top Breaking Changes (Quick View)

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).