TypeScript 4 → TypeScript 5

Upgrading from TypeScript 4 to 5 is a single major step with a well-supported path. The work is deleting removed flags, picking a decorator model, updating moduleResolution, and clearing the type errors stricter inference surfaces.

Version upgradeDifficulty: moderateEffort: 0.5–2 daysmedium risk

Last verified June 22, 2026 · Updated May 22, 2026

Migrating from TypeScript 4 to 5 is a single major step. There is no intermediate version to stop at — bump the compiler, fix the tsconfig, and clear the errors stricter inference surfaces.

Should you upgrade directly?

Yes. TypeScript 4 to 5 is one major step with no breaking runtime change of its own — the compiler still emits the JavaScript you target. The friction is removed compiler flags, the decorator model, and newly reported type errors, all of which surface immediately under tsc --noEmit.

Key differences

Decorators standardized on TC39; legacy decorators stay behind experimentalDecorators.
Flags deprecated in 5.0 and removed in 6.0: --out, --target ES3, --noImplicitUseStrict, --keyofStringsOnly, --charset.
--moduleResolution bundler and --verbatimModuleSyntax are now available.
const type parameters and enums-as-unions change some inference results.
Smaller package and faster builds; a newer minimum Node engine.

Files and patterns to inspect

Every tsconfig.json / tsconfig.*.json for removed compiler flags.
Classes using decorators and whether they rely on emitDecoratorMetadata.
package.json typescript version and all @types/* packages for duplicates.
Code relying on importsNotUsedAsValues (superseded by verbatimModuleSyntax).
isolatedModules assumptions if you switch to verbatimModuleSyntax.

Pre-migration checklist

Green tsc --noEmit on TypeScript 4 before starting
Lockfile committed; @types/* deduped
A dedicated upgrade branch
Decision recorded: TC39 vs legacy decorators

ℹ 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 without loosening strict flags or adding // @ts-ignore.

Migrate JavaScript to TypeScript — Related path
TypeScript 5 to TypeScript 6 Migration Guide — Next step forward
Upgrade to TypeScript 5 — Upgrade path to same target
Upgrade to TypeScript 6 — Related version path
Fix TypeScript Build Errors — Related workflow

Official sources

TypeScript 5.0 release — microsoft/TypeScript (reliability 92%)
TypeScript 5.0 Release Notes — typescriptlang.org (reliability 98%)

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 4 to TypeScript 5.

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 4 to TypeScript 5) 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.