VVersions.dev

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 · 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.
  • Removed flags: --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.

Related paths

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 inspectionRepo 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 removed-in-5.0 flags (--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 executionMigration 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.

Frequently asked questions

Can I skip straight to TypeScript 5 from 4?

Yes. There is no intermediate version — TS 4 to 5 is one major hop. Bump the compiler, update tsconfig, and resolve type errors in batches.

Will upgrading change my emitted JavaScript?

Only where you change target/module or decorator settings. TypeScript 5 emits the same JS you configure; the visible change is stricter type checking and a few removed flags, not new runtime behavior.