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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
The command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
File Explorer
16 files
Showing SKILL.md
SKILL.md
Source instructions · Read-only preview
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.
license
MIT
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
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)
Detect current version — run scripts/detect-ts-version.sh (reads package.json).
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.
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
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).
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
Detect — scripts/detect-ts-version.sh reports the installed version.
Audit — scripts/audit-ts7-breakers.sh detects breakers BEFORE any upgrade. scripts/ts6-deprecation-scan.sh extracts TS5xxx codes from tsc output.
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.
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).
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.
