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

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.