Upgrading to TypeScript 7: The tsconfig Changes That Break Builds

TypeScript 7 is the Go-based native compiler, and the speed is real: Microsoft's own benchmarks show full builds of large projects running roughly 8 to 12 times faster than on TypeScript 6. But teams that bump the version and hit enter often get a wall of errors on the first run, not because their code is wrong but because their tsconfig.json is. If you are planning a Q4 upgrade, here is what actually breaks, in the order you will hit it, and how to fix each one.

Why TypeScript 7 breaks old configs

TypeScript 6.0, released in March 2026, was designed as the bridge. Its release post called it "the bridge between TypeScript 5.9 and 7.0" and deprecated a long list of old options, while letting you silence those warnings with "ignoreDeprecations": "6.0".

TypeScript 7.0, released on 8 July 2026, removes the safety net. According to the TypeScript 7.0 announcement, the former deprecations are now hard errors, and 7.0 is compatible with 6.0's behaviour only when you are not using any deprecated options. So the recommended path is simple: get clean on 6.0 first, then switch.

Step 1: check for options that are now errors

Open your tsconfig.json (and any extended configs) and look for these. Each one is now an error in 7.0:

• "target": "es5". The lowest target is ES2015.

• "downlevelIteration" set at all.

• "moduleResolution": "node" (also called node10) or "classic".

• "module" set to amd, umd, systemjs or none.

• "baseUrl".

• "alwaysStrict": false.

• asserts on imports. Use with instead.

For most React and Next.js apps built in the last couple of years, the only one you are likely to find is baseUrl, usually sitting next to a paths block for @/ imports.

Fixing baseUrl and paths

Before:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

After: drop baseUrl and make each paths entry relative to the config file.

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

The 6.0 post recommends exactly this: replace baseUrl by adding prefixes to paths entries. Your bundler's alias config (Vite, webpack, Next.js) is separate, so check it still matches.

Fixing moduleResolution

If you are on "node", pick based on how your code runs:

• "bundler" if a bundler (Vite, webpack, Turbopack, esbuild) processes your imports. This is the usual choice for front-end apps.

• "nodenext" if Node runs your compiled output directly, such as a server or a published library.

Switching to nodenext can surface real issues, such as relative imports needing file extensions. That is a sign the old setting was hiding something, not that the new one is broken.

Step 2: the new defaults that change behaviour quietly

These do not error out, but they change what the compiler does if you were relying on the old default. From the 6.0 and 7.0 announcements:

• strict now defaults to true.

• module defaults to esnext.

• noUncheckedSideEffectImports defaults to true.

• rootDir defaults to the folder containing tsconfig.json.

• types defaults to [].

The last one causes the most confusion. Previously, TypeScript loaded every @types package in node_modules automatically. Now it loads none unless you say so. The symptom is errors like "Cannot find name 'process'" or "Cannot find name 'describe'" in files that compiled fine yesterday.

The fix is to list what you need:

{
  "compilerOptions": {
    "types": ["node", "vitest/globals"]
  }
}

You can set "types": ["*"] to restore the old behaviour, but an explicit list is better. It is faster and it stops a random @types package from leaking globals into your app.

If your tsconfig.json sits above src and you build to an outDir, also set "rootDir": "./src" explicitly so your output folder structure does not change.

Step 3: check your tools, not just your compiler

This is the part that catches teams out. TypeScript 7.0 ships without a programmatic API. In the team's words: "While TypeScript 7.0 is here, it does not ship with an API." A new API is expected in 7.1.

Anything that does import ts from "typescript" to read your code will not work against 7.0. That includes some linters, code generators, schema tools and custom build scripts. Microsoft's answer is a compatibility package, @typescript/typescript6, which re-exports the 6.0 API and provides a tsc6 binary, so the two can sit side by side.

A quick way to find out whether you need it, from a Next.js 16.3 upgrade write-up:

rg 'typescript' --glob '*.ts' --glob '*.tsx'

If nothing in your own code imports the compiler, and your lint and test tools work, you probably do not need the compatibility package. If you use Vue, Svelte, Astro, MDX or Angular templates, the announcement says to stay on 6.0 for editor support for now, because those integrations depend on a stable API.

Step 4: switch, then tune for CI

Once 6.0 is clean:

npm install -D typescript@7
npx tsc --noEmit

TypeScript 7 runs type-checking in parallel with four checker workers by default. On a small CI runner, that can be more than the machine has. You can set it explicitly:

npx tsc --noEmit --checkers 2

The announcement notes that different checker counts can occasionally surface order-dependent results, so pick a value and keep it the same locally and in CI.

A realistic upgrade order

1. Upgrade to 6.0. Remove ignoreDeprecations if you added it, and fix every warning.

2. Add an explicit types list and rootDir.

3. Check for compiler-API users in your toolchain.

4. Switch to 7.0 on a branch, run the full build, lint and tests.

5. Measure build times before and after. Your speedup will depend on your project; Microsoft's numbers are for large codebases.

Most of the work is in step 1, and it is work you would have had to do eventually anyway. Once the config is clean, TypeScript 7 is mostly a version bump with a very pleasant side effect: you stop waiting for the type checker.