Upgrade to TypeScript 6

TypeScript 6.0 (latest 6.0.3) is a recommended upgrade and the last release on the JavaScript-based compiler before the Go-native 7.0. Most breakage comes from the new compiler defaults — strict is now true, module is esnext, target is es2025, esModuleInterop is true, and types defaults to [] — plus the options 6.0 deprecates ahead of 7.0. Budget half a day to three days depending on how much your tsconfig relied on the old defaults.

Who should upgrade

• Projects on 5.x that want to land the modern defaults and clear deprecations before the 7.0 native compiler.
• Teams that want the smallest possible diff when 7.0 (Go) ships — 6.0 is the cleanup release.
• Anyone who wants strict mode and modern module/target defaults without hand-curating tsconfig.

Who should wait

• Projects that cannot absorb a strict-mode flip yet — pin "strict": false explicitly and schedule the ramp.
• Builds depending on removed options (outFile, moduleResolution classic, AMD/UMD/SystemJS module output) until they move to a bundler.
• Teams blocked on a dependency that has not published TypeScript 6-compatible types.

What changed

• strict defaults to true (was false) — the full strict family is on unless you opt out.
• module defaults to esnext (was commonjs); target defaults to es2025 (was es5, floats to current-year ES).
• moduleResolution defaults to bundler; esModuleInterop defaults to true.
• types defaults to [] (was every package under node_modules/@types); rootDir defaults to the tsconfig.json directory.
• noUncheckedSideEffectImports defaults to true; libReplacement defaults to false.
• Deprecated for removal in 7.0: target es5, moduleResolution node/node10/classic, module amd/umd/systemjs/none, baseUrl, esModuleInterop false, alwaysStrict false, and more — suppress with "ignoreDeprecations": "6.0".
• Removed outright: outFile and moduleResolution classic.

⚠ The default flips are the upgrade — pin what your build relies on

Because strict, module, target, moduleResolution, esModuleInterop, and types all change defaults, a project that inherited the old defaults will behave differently after the bump. Set each option explicitly in tsconfig.json to the value your build expects, then change them deliberately. The most disruptive is strict: true — expect new strictNullChecks and noImplicitAny errors on first typecheck.

ℹ 6.0 is the bridge to the Go-native 7.0

TypeScript 6.0 stays API-compatible with 5.9 and exists to get your code ready for 7.0, the native port written in Go. Resolve every deprecation 6.0 reports — "ignoreDeprecations": "6.0" silences them now but is not honored in 7.0. Preview the native compiler with the @typescript/native-preview package; the --stableTypeOrdering flag helps surface 6.0-to-7.0 ordering differences early.

Recommended upgrade path

Fast path for projects already on TypeScript 5.x

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

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

# 3. Diagnose under the new defaults without emitting
npx tsc --noEmit

# 4. Preview the Go-native 7.0 compiler (optional)
npm install -D @typescript/native-preview

Compatibility matrix

AI-assisted migration workflow

Upgrade this project to TypeScript 6. First, in tsconfig.json, make the previously-implicit defaults explicit (strict, module, target, moduleResolution, esModuleInterop, types, rootDir) so the bump does not change behavior silently. Then bump typescript to 6, dedupe @types/* packages, and run `tsc --noEmit`. Triage errors by code — the largest wave will come from strict: true. Address every deprecation 6.0 reports (you may temporarily set "ignoreDeprecations": "6.0") and remove any use of outFile or moduleResolution classic. Fix in small batches and run typecheck and tests after each step. Report the error count before continuing.

Safety: Incremental edits only. Pin the old defaults first, then change them deliberately. Pause for review after the tsconfig changes and after each batch of type fixes. Do not set "strict": false permanently to clear errors — schedule the ramp instead.

PR review checklist

• typescript is pinned to a single 6.x version (6.0.3 or later) in the lockfile
• strict, module, target, moduleResolution, esModuleInterop, and types are set explicitly in tsconfig
• outFile and moduleResolution classic are gone; module output uses a bundler where needed
• Every deprecation 6.0 reports is resolved, or tracked behind a removal-before-7.0 task
• No new // @ts-ignore or any was added to mask strict-mode errors

Rollback strategy

• Keep the explicit-defaults commit, the version bump, and the type fixes as separate commits.
• Revert to typescript@5 and reinstall if a blocking dependency or framework incompatibility appears.
• Hold the upgrade behind a branch until tsc --noEmit is clean under the new defaults and CI is green.

Common errors

• A flood of strictNullChecks / noImplicitAny errors — strict is now on by default; fix at the source, do not blanket-disable.
• Unexpected module/emit shape — module and target changed defaults; set them explicitly.
• 'Cannot find name' for ambient globals — types now defaults to [], so list the @types packages you actually need.
• Deprecation errors on baseUrl, moduleResolution node, etc. — resolve before 7.0; suppress temporarily with ignoreDeprecations.
• TS2307 cannot find module after the moduleResolution: bundler default — see the fix-typescript-build-errors workflow.

Related migration paths

• Migrate JavaScript to TypeScript — Earlier step in the upgrade chain
• TypeScript 4 to TypeScript 5 Migration Guide — Related version path
• TypeScript 5 to TypeScript 6 Migration Guide — Upgrade path to same target
• Upgrade to TypeScript 5 — Related version path
• Fix TypeScript Build Errors — Earlier step in the upgrade chain

Official sources

• Announcing TypeScript 6.0 — devblogs.microsoft.com (reliability 85%)
• TypeScript 6.0.3 release — microsoft/TypeScript (reliability 92%)
• TypeScript 6.0 Release Notes — typescriptlang.org (reliability 98%)
• TypeScript Documentation — 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: upgrade 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 (upgrade 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

Is the TypeScript 5 to 6 upgrade a hard upgrade?

It is more involved than upgrading within 5.x because 6.0 changes nine compiler defaults at once. The single biggest item is strict: true, which surfaces new errors immediately. Make the old defaults explicit first so the bump is behavior-preserving, then change them deliberately and clear errors in batches.

What is the relationship between TypeScript 6 and 7?

TypeScript 6.0 is the last release built on the JavaScript-based compiler and is API-compatible with 5.9. TypeScript 7.0 is a native rewrite in Go that is close to completion. Treat 6.0 as the cleanup step: resolve every deprecation it reports, because the "ignoreDeprecations": "6.0" escape hatch is not available in 7.0.

Can I keep CommonJS output on TypeScript 6?

Yes — module defaults to esnext, but you can still set "module": "commonjs" (or nodenext) explicitly. The defaults changed, not the available values. Set every option your build depends on rather than inheriting the new defaults.