What’s Changed and How to Update

TypeScript 6.0 Migration Guide: What’s Changed and How to Update

SitePoint TeamPublished inJavaScript·Programming·
August 15, 2026

The AI briefing for Developers

Stay up to date with AI tools, model releases, and developer workflows that matter.

Weekly. Free. One click to leave.

SitePoint Premium
Stay Relevant and Grow Your Career in Tech

• Premium Results
• Publish articles on SitePoint
• Daily curated jobs
• Learning Paths
• Discounts to dev tools

7 Day Free Trial. Cancel Anytime.

TypeScript 6.0 is expected to ship intentional breaking changes to foundational compiler defaults that will cause existing projects to fail compilation without targeted tsconfig.json and codebase updates. This guide covers every anticipated breaking change, explains the rationale behind each, and provides a step-by-step migration path with concrete tsconfig.json diffs, before/after code snippets, and validation commands.

Important: TypeScript 6.0 had not been officially released at the time of writing. All described changes are based on anticipated proposals and pre-release information. Verify every claim against the official release notes at https://devblogs.microsoft.com/typescript/ and the TypeScript GitHub releases page before migrating. Verify the minimum Node.js version required by TypeScript 6.0 in the official release notes before upgrading.

Table of Contents

The TypeScript 6.0 migration path touches how ambient types are resolved, how modules are located, and how the Temporal API surfaces in the type system. Each of these changes reflects a deliberate move by the TypeScript team toward explicitness and away from implicit, legacy behavior that has long been a

The target audience is intermediate TypeScript developers maintaining existing production projects who need to upgrade without surprises.

What’s Changed in TypeScript 6.0: Breaking Changes Overview

Before diving into each change individually, the following table provides a scannable reference of every breaking change, what it replaces, and the level of effort required to address it.

Summary Table of Breaking Changes

Impact Level scale: High = compiler errors expected in nearly all projects; Medium = errors in projects using the specific feature; Low = errors only in specific code patterns.

Breaking Change: types Now Defaults to []

UNVERIFIED — Claimed behavior:types will default to [] in TypeScript 6.0. This has not been confirmed in any official release note. Verify this against the official TypeScript 6.0 release notes before applying this change.

What Changed and Why

In every prior version of TypeScript, omitting the types field from tsconfig.json meant the compiler would automatically discover and include all @types/* packages found in node_modules/@types. This convenience came with downsides: phantom type pollution from transitive dependencies, unpredictable compilation behavior when someone installed unrelated @types packages, and difficulty reasoning about which type declarations were actually active in a given project.

TypeScript 6.0 is expected to change this default. When you omit types from tsconfig.json, it would now default to an empty array ([]), meaning the compiler includes no ambient type packages unless you list them explicitly. The rationale is straightforward: reduce implicit dependencies and improve compilation predictability. Projects must now declare exactly which ambient type packages they depend on.

Projects must now declare exactly which ambient type packages they depend on.

How This Breaks Your Project

Any project that relies on @types/node, @types/jest, @types/react, @types/express, or any other ambient type package without explicitly listing it in the types array will see immediate compilation errors after upgrading. The errors will reference missing global types, unknown modules, or undefined namespaces.

Consider a tsconfig.json that previously worked without a types field:

{"compilerOptions":{"target":"ES2022","module":"node16","moduleResolution":"node16","strict":true,"outDir":"./dist"},"include":["src"]}

After upgrading to TypeScript 6.0, a file like src/server.ts that references Buffer, process, or setTimeout (the Node.js global version) will produce errors such as:

error TS2304: Cannot find name 'Buffer'.error TS2304: Cannot find name 'process'.error TS2580: Cannot find name 'require'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node`.

Similarly, test files using Jest globals like describe, it, and expect without an explicit types entry will fail with Cannot find name 'describe' and related errors.

How to Fix It

The fix is to explicitly list every @types/* package the project depends on in the types array:

{"compilerOptions":{"target":"ES2022","module":"node16","moduleResolution":"node16","strict":true,"outDir":"./dist","types":["node","jest"]},"include":["src"]}

If typeRoots is set in your tsconfig, ensure the listed @types packages exist under those roots, not only under node_modules/@types.

To determine which @types/* packages are currently installed and should be listed, run the following cross-platform command:

node-e"const fs = require('fs');const dir = 'node_modules/@types';if (!fs.existsSync(dir)) {console.error('Directory not found: ' + dir);process.exit(1);}fs.readdirSync(dir).forEach(d => console.log('@types/' + d));"

Note: You may also see ls node_modules/@types | sed 's/^/@types//' | tr '
' ', ' suggested elsewhere. That pipeline is Unix/macOS only and will not work on Windows.

For a more precise audit, use tsc --listFiles with TypeScript 5.x before upgrading to capture which type declaration files the compiler previously auto-included. This output reveals every .d.ts file the compiler loaded, making it possible to identify which @types packages were silently active. Run this before running the upgrade command. If you have already upgraded, you can install 5.x in a temporary context using npx --package=typescript@5 tsc --listFiles | grep '@types'. Redirect the output and filter for @types:

npx tsc --listFiles|grep'node_modules/@types'> ts5-types-baseline.txtnpx tsc --listFiles|node-e"const chunks = [];process.stdin.on('data', d => chunks.push(d));process.stdin.on('end', () => {const lines = chunks.join('').split('').filter(l => l.includes('node_modules/@types'));require('fs').writeFileSync('ts5-types-baseline.txt', lines.join(''));});"

This produces a list of every ambient type file that was being loaded. Extract the package names and add them to the types array. Projects with separate tsconfig files for should ensure each config lists only the @types packages relevant to its scope. For example, @types/jest belongs in the test config, not the production

Breaking Change: moduleResolution: classic Removed

UNVERIFIED — Claimed removal of classic. This has not been confirmed in any official TypeScript 6.0 announcement. Verify against official release notes before making changes.

What Changed and Why

The classic module resolution strategy dates back to TypeScript’s earliest releases. It followed a simplistic algorithm: for relative imports, it looked for .ts and .d.ts files adjacent to the importing file; for non-relative imports, it walked up parent directories looking for the module in each ancestor folder. It did not understand node_modules, package.jsonexports fields, or any of the resolution conventions that Node.js and modern bundlers rely on.

TypeScript 6.0 is expected to remove classic entirely. Any tsconfig.json that sets “moduleResolution”: “classic”, whether directly orartup

Who Is Affected

This change primarily affects legacy codebases. Most modern projects already use node, node16, nodenext, or bundler as their module resolution strategy. However, you face risk beyond what your explicit config shows. Projects that extend older shared tsconfig base files (community-published or internal) may inherit "moduleResolution": "classic" without realizing it. Running tsc --showConfig before upgrading is the most reliable way to check the effective, resolved value.

How to Fix It

Replace "classic" with the appropriate modern resolution strategy. The choice depends on the project’s runtime and build tooling:

Note: The code examples below use // comments for illustration. Do not include // comments in files named tsconfig.json unless your toolchain explicitly supports JSONC (JSON with Comments). TypeScript’s own parser does support JSONC in tsconfig.json, but other tools that consume your tsconfig (build scripts, CI tools, linters) may not.

// Before (TypeScript 5.x){"compilerOptions": {"moduleResolution": "classic","module": "commonjs"}}// After — Node.js projects (TypeScript 6.0){"compilerOptions": {"moduleResolution": "node16","module": "node16"}}// After — Bundled front-end projects (TypeScript 6.0){"compilerOptions": {"moduleResolution": "bundler","module": "esnext"}}

• Projects running directly on Node.js, where output must conform to Node’s module resolution rules (including package.jsonexports and mandatory file extensions in ESM), should use node16 or nodenext.
• For CommonJS-only Node.js projects that do not use ESM, "moduleResolution": "node" remains a valid intermediate step if node16‘s extension requirements are disruptive.
• Front-end projects processed by webpack, Vite, esbuild, or similar tools should use bundler, since the bundler handles resolution and the TypeScript output is not consumed directly by a runtime. The bundler strategy is more permissive (it allows extensionless relative imports, for example) because it delegates resolution to the bundler.

Note:moduleResolution: bundler is incompatible with module: commonjs. Ensure module is set to esnext, preserve, or another ESM-compatible value when using bundler.

Breaking Change: Temporal API Types Built In

UNVERIFIED — Claimed inclusion of Temporal types in lib.d.ts. TC39 Temporal is still at Stage 3 (approaching Stage 4), and TypeScript has not confirmed this inclusion in any official release note. Removing polyfills based on this claim risks runtime failures. Verify against official release notes before acting.

What Changed and Why

The TC39 Temporal proposal provides a modern replacement for JavaScript’s Date object, introducing types like Temporal.PlainDate, Temporal.ZonedDateTime, Temporal.Duration, and Temporal.Instant. TypeScript 6.0 is expected to include these type declarations in its built-in lib.d.ts when the lib or target setting includes ES2024 or later. Previously, developers who needed Temporal types used third-party packages such as @js-temporal/polyfill, which shipped their own type declarations, or wrote custom ambient declarations.

Potential Conflicts

Projects using polyfill packages with their own Temporal type declarations will encounter duplicate identifier errors when the built-in types overlap with the polyfill’s global augmentations. The error typically looks like this:

error TS2300: Duplicate identifier 'PlainDate'.node_modules/@js-temporal/polyfill/dist/index.d.ts:45:14lib/lib.es2024.temporal.d.ts (line numbers will vary by TypeScript version)error TS2300: Duplicate identifier 'ZonedDateTime'.node_modules/@js-temporal/polyfill/dist/index.d.ts:89:14lib/lib.es2024.temporal.d.ts (line numbers will vary by TypeScript version)

The conflict arises because both the polyfill’s .d.ts files and TypeScript’s built-in lib.es2024.temporal.d.ts declare types in the global Temporal namespace.

How to Fix It

The resolution depends on whether the project still needs the polyfill at runtime. If the target environment natively supports the Temporal API, you may remove the polyfill and rely on the built-in types:

Warning: Only remove the polyfill if your minimum deployment target natively supports the Temporal API. As of 2025, no Node.js LTS release and no major browser ships Temporal as stable. Verify native support at https://caniuse.com/temporal and by running node -e "console.log(typeof Temporal)" on your target runtime before removing.

npm uninstall @js-temporal/polyfill

If the polyfill is still needed for runtime support (because the deployment target lacks native Temporal), adjust the polyfill’s usage to avoid global augmentation. Import from the polyfill’s module scope rather than relying on its global Temporal declaration:

import'@js-temporal/polyfill';const date = Temporal.PlainDate.from('2025-01-15');import{ Temporal }from'@js-temporal/polyfill';const date = Temporal.PlainDate.from('2025-01-15');

If the project uses the polyfill’s side-effect import (import '@js-temporal/polyfill') across multiple files to augment the global Temporal, all such files must be updated to use the scoped named import instead. Consider creating a single barrel re-export module (e.g., src/temporal.ts) that re-exports from the polyfill, so only one import site needs to change if the polyfill is later removed.

Your lib array or target setting may not even include ES2024+. If the project targets ES2022 or earlier, the built-in Temporal types are not included, and the conflict does not apply. Run tsc --showConfig to verify the effective lib value.

Other Notable Changes

Stricter Type Narrowing in Control Flow

TypeScript 6.0 refines control flow analysis in several edge cases. Code that previously passed type checking may now surface errors where the compiler applies more precise narrowing. The TypeScript team has not fully documented the specific patterns yet. No reliable minimal example is available; we will update this section when the release notes publish affected patterns. The fix is typically to add explicit type annotations or adjust conditional logic to match the compiler’s improved understanding.

Deprecations and Removals

TypeScript 5.x deprecated several compiler options; 6.0 removes them. Any tsconfig.json containing these options will produce an error rather than a warning. A complete list of removed options is not available at the time of writing; consult the official TypeScript 6.0 release notes at https://devblogs.microsoft.com/typescript/ for the exhaustive list and recommended replacements.

Step-by-Step Migration Checklist

Prerequisites

• Confirm TypeScript 6.0 is published on npm with npm show typescript dist-tags --json before proceeding.
• Verify the minimum Node.js version required by TypeScript 6.0 in the official release notes.
• Pre-upgrade baseline: Before upgrading, capture your current compiler output for later comparison (see steps 2-3 below).

The following checklist covers the complete migration process in order of priority:

1. Capture pre-upgrade baselines (before upgrading TypeScript):
   • npx tsc --noEmit --extendedDiagnostics > ts5-baseline.txt 2>&1
   • Capture the @types file list baseline (see code block below)
2. Update TypeScript: npm install typescript@6.0.0 (replace 6.0.0 with the exact version from npm show typescript dist-tags --json; typescript@6 is not a valid dist-tag).
3. Run tsc: Capture the initial error output before making any changes. This serves as the baseline for tracking progress.
4. Audit tsconfig.json for the types field: Add an explicit types array listing all required @types/* packages. Use the cross-platform Node.js command shown above or the pre-upgrade --listFiles baseline to identify what was previously auto-included.
5. Check moduleResolution: Replace classic with node16, nodenext, node, or bundler as appropriate. Run tsc --showConfig to check inherited values from extended configs.
6. Search for third-party Temporal type packages: Remove or scope them to avoid duplicate identifier conflicts with the built-in lib.es2024.temporal.d.ts. Do not remove runtime polyfills unless your deployment target natively supports Temporal.
7. Review extended/shared tsconfig base files: Inherited values for types, moduleResolution, and deprecated options can silently introduce breaking changes.
8. Run the full test suite: Look for both compilation errors and runtime behavior changes. Type-only changes can mask runtime issues.
9. Update CI pipeline TypeScript version: Ensure CI installs TypeScript 6.0 and that all pipeline stages pass.
10. Update editor/IDE TypeScript version: In VS Code, set "typescript.tsdk": "node_modules/typescript/lib" in .vscode/settings.json (workspace-level, not user settings) to ensure the workspace uses the project-local TypeScript 6.0 installation.
11. Commit and tag the migration: Tag the commit for easy rollback if downstream issues emerge.

Capture the @types file list baseline:

npx tsc --listFiles|grep'node_modules/@types'> ts5-types-baseline.txtnpx tsc --listFiles> ts5-listfiles.txt 2>&1node-e"const fs = require('fs');const lines = fs.readFileSync('ts5-listfiles.txt', 'utf8').split('').filter(l => l.includes('node_modules/@types'));fs.writeFileSync('ts5-types-baseline.txt', lines.join(''));"

Recommended Migration Order

Prioritize the types default change first. It has the highest blast radius, affecting virtually every project that relies on any @types/* package. Address moduleResolution second, as it is straightforward to detect and fix. Handle Temporal type conflicts last, since they only affect projects targeting ES2024+ with specific polyfill packages installed.

Validating Your Migration

Compiler-Level Validation

After applying all changes, run the compiler in check-only mode using your project’s own tsconfig.json settings:

npx tsc --noEmit

Do not pass --strict here unless you intend to override your tsconfig’s strict configuration. The --strict CLI flag overrides (not supplements) tsconfig.json settings, and may produce a different set of errors than your project’s actual configuration would.

A clean output (no errors, no warnings) confirms that the type system is satisfied with the updated configuration. For deeper inspection of how type resolution behaves under the new defaults, use the --extendedDiagnostics flag:

npx tsc --noEmit--extendedDiagnostics> ts6-result.txt 2>&1

This outputs detailed information about file counts, resolution times, and which type declaration files the compiler loaded. Compare against the pre-migration baseline you captured before upgrading:

diff ts5-baseline.txt ts6-result.txt

Note on Windows:diff is not available in Windows CMD. Use git diff --no-index ts5-baseline.txt ts6-result.txt (available if Git is installed) or compare files in your editor. Alternatively, use WSL or Git Bash.

This confirms that the correct @types packages are being resolved and that no unexpected files are entering the compilation.

Runtime and Test Validation

Type-level correctness does not guarantee runtime correctness. Changes to type narrowing, module resolution, or Temporal typeme. Run the full integration and unit test suites after migration. Pay particular attention to tests involving dynamic imports, conditional type guards, and any code paths that interact with the Temporal API

Migration Summary

TypeScript 6.0’s breaking changes are deliberate improvements to defaults and consistency, not arbitrary churn. The shift to explicit types, the removal of the obsolete classic resolution strategy, and the inclusion of Temporal API types all reduce implicit behavior that historically caused hard-to-diagnose issues. With the checklist and tsconfig.json adjustments detailed above, projects with a single tsconfig and fewer than five @types dependencies should complete the migration in a few hours. Monorepos or projects with many @types dependencies and polyfills should budget a day or more per workspace root. Check the official TypeScript 6.0 release notes for anything this guide doesn’t cover.

Sharing our passion for building incredible internet things.