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)

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

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

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

Package Versions (Verified 2026-07-09)