VVersions.dev

Upgrade to TypeScript 5

TypeScript 5 is a recommended upgrade for projects on 4.x. The risk is concentrated in removed compiler flags, the decorator model switch, and stricter inference — not in rewriting application code.

Version upgradeDifficulty: moderateEffort: 0.5–2 days for a typical projectmedium risk

Last verified · Updated May 22, 2026

TypeScript 5 is a recommended upgrade for projects on 4.x. Most breakage comes from the decorator standardization and the flags deprecated in 5.0 (removed in 6.0) — not from rewriting code. Budget half a day to two days depending on decorator usage and tsconfig sprawl.

ℹ TypeScript 6 is now the current line

TypeScript 6.0 (latest 6.0.3, March 2026) is the recommended target and the last JavaScript-based release before the Go-native 7.0. If you are already on a recent 5.x, follow the TypeScript 5 to 6 path; use this 4-to-5 hub first only if you are still on 4.x. Land on 5.x, get a clean tsc --noEmit, then continue to 6.

Who should upgrade

  • Projects on 4.x wanting a smaller compiler, faster builds, and const type parameters.
  • Libraries that want enums emitted as union types and stricter inference.
  • Teams adopting the standard TC39 decorators instead of the legacy experimental form.

Who should wait

  • Projects with heavy legacy-decorator usage (NestJS, TypeORM, older Angular) until the framework confirms TS 5 support.
  • Builds still pinned to Node versions below the TypeScript 5 engine requirement.

What changed

  • Decorators standardized on the TC39 Stage 3 proposal; legacy decorators remain behind experimentalDecorators.
  • const type parameters for more precise inference of literal types.
  • --moduleResolution bundler for projects bundled by Vite/esbuild/webpack.
  • --verbatimModuleSyntax replaces importsNotUsedAsValues and isolatedModules import elision rules.
  • Enums behave more like unions of their members; smaller npm package and faster builds.
  • Deprecated flags (no effect from 5.5, error in 6.0): --out, --target ES3, --noImplicitUseStrict, --keyofStringsOnly, --charset, and others.

⚠ Decide on one decorator model before upgrading

TS 5.0 ships standard TC39 decorators without a flag. They are NOT interchangeable with legacy decorators. If your code or framework relies on emitDecoratorMetadata/experimentalDecorators, keep those flags set and do not mix the two models in one project.

Fast path for projects already on TypeScript 4.x

# 1. Bump TypeScript
npm install -D typescript@5

# 2. Check for duplicate type packages
npm ls typescript
npm why @types/node

# 3. Diagnose without emitting
npx tsc --noEmit

Compatibility matrix

ConcernTypeScript 4.xTypeScript 5.x
DecoratorsLegacy (experimentalDecorators)TC39 standard by default; legacy still available
--moduleResolution bundlerUnavailableAvailable
--verbatimModuleSyntaxUnavailableAvailable (supersedes importsNotUsedAsValues)
--out / --target ES3AllowedDeprecated in 5.0; no-op in 5.5; error in 6.0
const type parametersUnavailableAvailable

AI-assisted migration workflow

Upgrade this project to TypeScript 5. First inspect tsconfig.json for the flags deprecated in 5.0 and removed in 6.0 (--out, --target ES3, --keyofStringsOnly, --noImplicitUseStrict, --charset) and any decorator usage. Then bump typescript, dedupe @types/* packages, set moduleResolution to bundler or node16, and run `tsc --noEmit`. Triage errors by code, fix in small batches, and run typecheck and tests after each step. Report the error count before continuing.

Safety: Incremental edits only. Pause for review after the tsconfig changes and after each batch of type fixes. Do not loosen strict flags to clear errors.

PR review checklist

  • typescript is pinned to a single 5.x version in the lockfile
  • Flags deprecated in 5.0 (removed in 6.0) were deleted from every tsconfig.*.json
  • A single decorator model is in use; experimentalDecorators set intentionally
  • moduleResolution matches how the project is actually bundled
  • No new // @ts-ignore was added to mask real errors

Rollback strategy

  • Keep the version bump, tsconfig changes, and type fixes in separate commits.
  • Revert to typescript@4 and reinstall if a blocking framework incompatibility appears.
  • Hold the upgrade behind a branch until tsc --noEmit is clean and CI is green.

Common errors

  • Unknown compiler option after removing a now-deleted flag — delete it from tsconfig.json.
  • Decorator signature errors — you are mixing legacy and TC39 decorators.
  • TS2307 cannot find module after a moduleResolution change — see the fix-typescript-build-errors workflow.

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: upgrade 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 (upgrade 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

Is the TypeScript 4 to 5 upgrade a hard upgrade?

For most projects it is straightforward — the main work is deleting the compiler flags 5.0 deprecated (and 6.0 removed), confirming your decorator model, and clearing the type errors that stricter inference surfaces. Effort scales with how much legacy-decorator and custom tsconfig surface you have.

Do I have to switch to the new TC39 decorators?

No. Legacy decorators still work behind experimentalDecorators, and frameworks like NestJS and TypeORM still rely on them. Keep that flag set and migrate decorators only when your framework supports the standard model.