VVersions.dev

TypeScript 5 → TypeScript 6

Upgrading from TypeScript 5 to 6 is one major step, but 6.0 changes nine compiler defaults at once. The work is making the old defaults explicit, flipping to the new ones deliberately (strict first), resolving deprecations ahead of 7.0, and clearing the type errors strict mode surfaces.

Version upgradeDifficulty: moderateEffort: 0.5–3 dayshigh risk

Last verified · Updated May 22, 2026

Migrating from TypeScript 5 to 6 is a single major step, but unlike a within-5.x bump it changes the compiler defaults. There is no intermediate version — pin the old defaults, bump the compiler, flip to the new defaults deliberately, and clear the errors strict mode surfaces.

Should you upgrade directly?

Yes. TypeScript 5 to 6 is one major step and stays API-compatible with 5.9. The friction is the changed defaults (strict, module, target, moduleResolution, esModuleInterop, types), the options 6.0 deprecates ahead of 7.0, and the handful it removes outright (outFile, moduleResolution classic). All of it surfaces immediately under tsc --noEmit, so the upgrade is observable rather than runtime-surprising.

Key differences

  • strict defaults to true; the full strict family is on unless you opt out.
  • module → esnext, target → es2025, moduleResolution → bundler, esModuleInterop → true.
  • types defaults to [] (was all @types/* packages); rootDir defaults to the tsconfig.json directory.
  • noUncheckedSideEffectImports → true; libReplacement → false.
  • outFile and moduleResolution classic are removed; AMD/UMD/SystemJS module output is dropped.
  • Many options are deprecated for removal in the Go-native 7.0 — resolve them now.

Files and patterns to inspect

  • Every tsconfig.json / tsconfig.*.json that relied on implicit strict/module/target/types defaults.
  • Build configs using outFile or moduleResolution classic (must move to a bundler / modern resolution).
  • Ambient global usage that depended on types pulling in all @types/* packages.
  • package.json typescript version and all @types/* packages for duplicates.
  • Any option flagged deprecated by 6.0 (baseUrl, moduleResolution node/node10, esModuleInterop false, alwaysStrict false).

⚠ Make defaults explicit before you bump

The 5-to-6 jump changes nine defaults. Run tsc --showConfig on 5.x, then write those values explicitly into tsconfig.json before installing TypeScript 6 so the bump itself changes nothing. Flip to the new defaults one at a time afterward — strict: true will produce the largest error wave.

Pre-migration checklist

  • Green tsc --noEmit on TypeScript 5 before starting
  • Effective config captured via tsc --showConfig and pinned explicitly
  • Lockfile committed; @types/* deduped
  • A dedicated upgrade branch
  • Plan recorded for the strict-mode ramp and for resolving 6.0 deprecations before 7.0

ℹ Use tsc --noEmit as your migration dashboard

Run npx tsc --noEmit after every change. The error count is your progress bar — drive it to zero by fixing types at the source, not by reverting to "strict": false or adding // @ts-ignore. Resolve deprecations too: "ignoreDeprecations": "6.0" is a temporary bridge, not a destination, because 7.0 ignores it.

Official sources

Copy-ready AI prompts

Structured prompts for an AI coding assistant. Inspect first, then execute incrementally, and keep a human in the review loop.

Repo inspection: Repo inspection prompt

You are helping with a TypeScript migration: TypeScript 5 to TypeScript 6.

Do not edit files yet. First inspect the repository and report:
1. The exact typescript version in package.json and the lockfile, plus every @types/* package and whether duplicates resolve to different versions (run `npm ls typescript` and `npm why @types/node`).
2. The active tsconfig.json options: strict flags, moduleResolution, target/module, experimentalDecorators, isolatedModules, skipLibCheck, and any flags deprecated in 5.0 / removed in 6.0 (--out, --target ES3, --keyofStringsOnly, --charset, --noImplicitUseStrict).
3. Files using decorators and whether they rely on the legacy (experimentalDecorators) model.
4. The build/typecheck command and whether the project emits with tsc or a bundler.
5. Any // @ts-ignore / // @ts-expect-error suppressions and any JS files type-checked via allowJs/checkJs.

Return: a risk summary, the highest-risk files, a suggested migration order, the commands to run before editing, and any questions that need human confirmation.

Safety: Inspection only. The agent must not modify files in this step.

Works with Claude Code, Cursor, GitHub Copilot.

Migration execution: Migration execution prompt

Perform the migration (TypeScript 5 to TypeScript 6) one concern at a time.

Work in this order and pause for review after each: (1) bump the typescript devDependency and dedupe @types/* packages, (2) update tsconfig.json — remove deleted flags and set moduleResolution to bundler or node16 as appropriate, (3) run `tsc --noEmit` and triage errors by code, (4) fix type errors in small batches, (5) reconcile decorators to a single model.

After each step run `tsc --noEmit` and the project's test command, and report the error count and results before continuing. Do not refactor unrelated code or loosen strictness to make errors disappear.

Safety: Apply changes incrementally and keep each step reviewable. Never silence errors with broad any or // @ts-ignore to force a green build.

Works with Claude Code, Cursor, GitHub Copilot.

Test plan

Commands

  • npx tsc --noEmit
  • npm run lint
  • npm test -- --watch=false
  • npm run build

Manual checks

  • Decorators: exercise any class using decorators (DI, ORM entities, validators) at runtime.
  • Emit: confirm the compiled output and declaration (.d.ts) files match the previous shape.
  • Module resolution: verify imports of ESM/CJS dependencies still resolve at runtime.

Regression risks

  • Mixed legacy and TC39 decorators in the same project.
  • skipLibCheck masking type errors inside dependency .d.ts files.
  • Duplicate @types/* packages resolving to conflicting versions.

Acceptance criteria

  • tsc --noEmit passes with zero errors on the target version.
  • No new // @ts-ignore or // @ts-expect-error were added to mask real errors.
  • Build and test suites pass on the upgraded toolchain.

Frequently asked questions

Can I skip straight to TypeScript 6 from 5?

Yes. There is no intermediate version — TS 5 to 6 is one major hop. The catch is that 6.0 changes nine defaults at once, so make them explicit first, then flip to the new ones deliberately and resolve type errors in batches.

Will upgrading change my emitted JavaScript?

It can, because module and target defaults changed (commonjs → esnext, es5 → es2025). Set module and target explicitly to the output your runtime/bundler expects and the emit stays under your control; the visible change is otherwise stricter type checking and resolved deprecations.

Do I have to fix every deprecation 6.0 reports?

Not to ship on 6.0 — you can suppress them with "ignoreDeprecations": "6.0". But you should, because TypeScript 7.0 (the Go-native port) removes those options and no longer honors the suppression. Treating 6.0 as the cleanup release makes the 7.0 jump trivial.