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 May 20, 2026 · Updated May 22, 2026

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

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

Recommended upgrade path

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

Concern	TypeScript 4.x	TypeScript 5.x
Decorators	Legacy (experimentalDecorators)	TC39 standard by default; legacy still available
--moduleResolution bundler	Unavailable	Available
--verbatimModuleSyntax	Unavailable	Available (supersedes importsNotUsedAsValues)
--out / --target ES3	Allowed	Removed
const type parameters	Unavailable	Available

Migration executionAI-assisted migration workflow

Upgrade this project to TypeScript 5. First inspect tsconfig.json for removed flags (--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
Removed compiler flags 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

GitHub releaseTypeScript 5.0 releasemicrosoft/TypeScriptreliability 92%
Backs the breaking-change and migration-step claims.
ChangelogTypeScript 5.0 Release Notestypescriptlang.orgreliability 98%
Backs the breaking-change and migration-step claims.
Official docsTypeScript Documentationtypescriptlang.orgreliability 98%
Backs the breaking-change and migration-step claims.

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: 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 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 (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 removed compiler flags, 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.