TypeScript 7 Migration Guide: Native tsc, Breaking Defaults, and Why MDX Projects May Need to Wait

TypeScript 7.0 is a stable release, but it is not a routine compiler update. Microsoft rewrote the compiler and language service in Go, introduced parallel type checking and builds, changed several defaults, and removed old options that TypeScript 6 had only deprecated. The new compiler is designed to preserve TypeScript 6 type-checking behavior, yet the packaging and API story creates an important boundary for real projects.

The most important limitation is explicit in the official announcement: TypeScript 7.0 does not ship a stable programmatic compiler API. Tools that embed TypeScript—especially workflows involving MDX, Vue, Astro, Svelte, Angular templates, custom transformers, or compiler-based loaders—may need TypeScript 6 until the new API arrives.

That means “7.0 is GA” and “every TypeScript project should replace its compiler today” are not equivalent statements.

TL;DR

• TypeScript 7.0.2 is stable and uses the new native compiler.
• Migrate cleanly to TypeScript 6 first; 7 turns several 6.0 deprecations into errors.
• TypeScript 7 has no stable compiler API, so embedded-language and MDX tooling may need TypeScript 6.
• Use @typescript/typescript6 beside TypeScript 7 when tools still need the old API.
• Benchmark your repository and verify declarations, project references, editor behavior, and framework builds before switching CI.

What changed between 5.9, 6.0, and 7.0

TypeScript 6 is the transition release. It keeps the JavaScript implementation while warning about options and syntax that the native compiler removes. TypeScript 7 is the new Go implementation and enforces the new baseline.

Skipping the TypeScript 6 diagnostics makes a TypeScript 7 failure harder to interpret. A safer path is to make the project compile cleanly on 6 without ignoreDeprecations, then evaluate 7.

Establish a baseline

Record the existing compiler version and build commands:

npx tsc --version
npx tsc --noEmit

For a monorepo:

npx tsc --build --verbose

Also run the framework build. A plain tsc result does not exercise MDX loaders, Next.js plugins, declaration bundlers, test transformers, or custom code generation.

yarn build

Keep the baseline log and timing. Performance is useful, but correctness and tool compatibility decide whether the upgrade can ship.

Migrate to TypeScript 6 first

Install the latest supported TypeScript 6 release for migration work:

npm install --save-dev typescript@^6.0.3

Run the compiler without hiding the new deprecations:

npx tsc --noEmit

If the configuration temporarily contains this:

{
  "compilerOptions": {
    "ignoreDeprecations": "6.0"
  }
}

remove it before considering the project ready for TypeScript 7. The option can help teams stage work, but TypeScript 7 does not support the deprecated configuration it conceals.

Review the new defaults

TypeScript 7 adopts stricter defaults. Existing tsconfig.json files often state some of these explicitly, but generated or minimal configurations can change behavior.

Important defaults include:

• strict: true;
• module: "esnext";
• a modern default target;
• noUncheckedSideEffectImports: true;
• stableTypeOrdering: true;
• rootDir: "./";
• types: [];
• libReplacement: false.

The rootDir and types changes are especially likely to surprise established repositories.

Before:

{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler"
  },
  "include": ["src"]
}

After an explicit migration:

{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler",
    "rootDir": "./src",
    "types": ["node", "jest"],
    "strict": true
  },
  "include": ["src"]
}

Do not copy types blindly. List only the global declaration packages the project actually needs. Browser-only packages may need no Node globals, while tests may use a separate tsconfig.test.json.

Replace removed module settings

Several long-deprecated settings are no longer supported:

• moduleResolution: "node" or "node10";
• moduleResolution: "classic";
• module: "amd", "umd", "systemjs", or "none";
• target: "es5";
• baseUrl;
• downlevelIteration;
• disabling esModuleInterop or allowSyntheticDefaultImports.

For a modern bundler:

{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

For Node.js code whose runtime behavior should follow Node's package rules:

{
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext"
  }
}

Choose based on the runtime and build system. bundler is not a universal replacement for every Node.js service.

Replace import assertions

Import assertions use with rather than asserts.

Before:

import metadata from './metadata.json' asserts { type: 'json' }

After:

import metadata from './metadata.json' with { type: 'json' }

Runtime support still matters. TypeScript accepting syntax does not guarantee that an older Node.js runtime or bundler understands it.

Understand the missing compiler API

Many tools do more than execute tsc. They import functions from the typescript package to parse source files, create programs, transform syntax, or power language integrations. TypeScript 7.0 does not provide the stable API those tools expect.

This affects:

• custom TypeScript transformers;
• some webpack or test loaders;
• declaration and API extraction tools;
• framework template compilers;
• embedded languages;
• editor plugins;
• MDX pipelines that rely on TypeScript programmatic services.

The official migration strategy is to run TypeScript 7 and keep TypeScript 6 available through a compatibility package.

npm install --save-dev \
  @typescript/native@npm:typescript@^7.0.2 \
  typescript@npm:@typescript/typescript6@^6.0.3

This produces a TypeScript 7 tsc through the alias while retaining the TypeScript 6 package/API for dependent tooling. Exact script names should be checked after installation:

npx tsc --version
npx tsc6 --version

An explicit package configuration makes the intent clearer:

{
  "devDependencies": {
    "@typescript/native": "npm:typescript@^7.0.2",
    "typescript": "npm:@typescript/typescript6@^6.0.3"
  },
  "scripts": {
    "typecheck:native": "tsc --noEmit",
    "typecheck:compat": "tsc6 --noEmit"
  }
}

Validate these commands in the actual package manager because binary alias behavior can vary.

Why an MDX project may wait

The TypeScript team specifically notes that MDX, Vue, Astro, Svelte, and similar embedded-language workflows may not yet be able to use TypeScript 7 fully. These ecosystems commonly rely on the compiler API or language-service integration.

For an MDX-based Next.js site, adoption should therefore require:

1. the content compilation pipeline succeeds;
2. all MDX plugins load without importing an incompatible TypeScript API;
3. generated route and content types are correct;
4. the Next.js production build succeeds;
5. editor diagnostics remain usable;
6. CI runs the intended compiler rather than silently falling back.

Until those conditions are proven, remaining on TypeScript 5.9 is not ideal because it skips the migration bridge. Moving to TypeScript 6 may be the better intermediate state.

Test project references and declarations

TypeScript 7 parallelizes type checking and project builds. Monorepositories should verify deterministic output and resource usage.

npx tsc --build --clean
npx tsc --build --verbose

Compare emitted declaration files:

git diff -- '**/*.d.ts'

If the CI runner has limited CPU or memory, experiment with controlled worker counts:

npx tsc --build --checkers 2 --builders 2

Avoid maximizing both values automatically. Builder and checker parallelism can multiply the number of workers and increase peak resource usage.

For debugging or comparison:

npx tsc --singleThreaded --noEmit

Use a fixed configuration in CI after measuring it. Local developer machines and small hosted runners may need different settings.

Verify JavaScript projects too

TypeScript 7 also changes checking behavior for JavaScript and JSDoc. Repositories using allowJs or checkJs should test:

• JSDoc typedefs;
• constructor-like functions;
• enum annotations;
• Closure-style function types;
• prototype assignment patterns;
• type references to values.

Run the type checker against representative JavaScript packages rather than assuming a TypeScript-only migration guide covers them.

A staged CI strategy

Run the existing and native compilers side by side before switching the required check.

steps:
  - run: npm ci
  - run: npm run typecheck:compat
  - run: npm run typecheck:native
    continue-on-error: true
  - run: npm run build

After the native compiler and complete framework build remain stable, make the TypeScript 7 job required. Keep TypeScript 6 only for tools that still import its API.

The migration is complete only when:

• TypeScript 6 reports no hidden deprecations;
• TypeScript 7 reports no new errors;
• declarations and generated files are reviewed;
• tests and the framework build pass;
• editor and watch mode work;
• embedded-language tooling has a supported path;
• CI resource usage remains acceptable.

Adopt now or wait?

Adopt TypeScript 7 now when:

• the project primarily invokes tsc;
• no critical tool imports the compiler API;
• TypeScript 6 migration warnings are resolved;
• framework and editor integrations pass;
• build performance is a meaningful bottleneck.

Use a side-by-side setup when:

• CLI type checking can use 7;
• linting, MDX, or code generation still needs the TypeScript 6 API;
• the team wants native compiler benefits without breaking the toolchain.

Wait on a full replacement when:

• the project depends on embedded-language tooling;
• custom transformers or loaders require typescript;
• the framework has not documented compatibility;
• the repository does not compile cleanly on TypeScript 6;
• the performance benefit does not justify a split toolchain yet.

Official sources

• Announcing TypeScript 7.0
• Announcing TypeScript 6.0
• TypeScript 6.0 release notes
• TypeScript releases

TypeScript 7 is a production release with an intentionally incomplete compatibility surface. Treat the native compiler as a tested build component, not a one-line package bump, and keep TypeScript 6 available wherever the ecosystem still needs its API.