SuperAPI AI Directory
Partner中文AI newsFavorites
Skillstypescript-migration

typescript-migration

Coding & development

View repository

Updated 10-16 01:09

About this skill

TypeScript Migration

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

Status

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.