TypeScript 7 Migration Guide: Upgrade to the 10x Faster Compiler

For more than ten years, the TypeScript compiler was written in TypeScript itself. That changed with TypeScript 7. Microsoft rewrote the whole compiler in Go, and the result is a native tool that type-checks most projects about 8 to 12 times faster while using less memory. If you have ever waited a minute for tsc to finish, or watched your editor freeze on a large project, this upgrade is for you.

But TypeScript 7 is not just “the same thing, faster”. It also removes old settings (like baseUrl and target: "es5"), turns on strict mode by default, and does not yet ship the programmatic API that some tools (typescript-eslint, Vue, Svelte, Angular) depend on. In this guide you will learn, step by step, how to move a real project to TypeScript 7 without breaking your build, your editor, or your CI pipeline.

What is TypeScript 7?

TypeScript 7 is the first stable release of the native TypeScript compiler, announced by Microsoft in July after a beta in April and a release candidate in June. During development it was called “Project Corsa” and was tested through a package named @typescript/native-preview with a tsgo command. Now it is simply the typescript package, and the command is still tsc.

The important thing to understand is that the language did not change much. Your .ts files, interfaces, generics and type tricks all work the same way. What changed is the engine that reads and checks your code. The team ported the existing compiler code to Go line by line, so type-checking results stay almost identical to TypeScript 6.

TypeScript 6.0 (released in March) is the “bridge” version. It is the last version built on the old JavaScript codebase, and its main job is to warn you about every setting that TypeScript 7 removes. That is why the smoothest upgrade goes 5.x → 6.0 → 7.

Why is TypeScript 7 so much faster?

There are two big reasons:

1. Native code. Go compiles to machine code. There is no JavaScript engine warming up, no just-in-time compilation and less memory overhead for every object the compiler creates.
2. Real parallelism. Go makes it easy to run work on many CPU cores that share memory. TypeScript 7 parses files in parallel and splits type-checking across several “checker” workers (four by default). The old compiler ran on a single thread.

Here are some real full-build numbers published by the TypeScript team:

Memory use also dropped by about 6% to 26% in the team’s tests. For a small side project you may only save a second or two, but on a large company monorepo the difference can be minutes per build and much faster CI runs.

Check before you upgrade

Spend five minutes answering these questions before you touch package.json. They decide whether you can switch fully today or should run both versions for a while.

• Does your project use typescript-eslint with type-aware rules? It uses the TypeScript programmatic API, which TypeScript 7.0 does not ship yet.
• Do you use Vue, Svelte, Astro, MDX or Angular templates? Tools such as vue-tsc and Angular’s template type-checking also need the old API.
• Do you use a webpack loader that runs the compiler (for example ts-loader in type-checking mode)? Same story.
• Does your tsconfig use baseUrl, target: "es5" or moduleResolution: "node"? These must be changed first.
• Do you rely on global types from @types/* like process, describe or expect? You will need to list them in types.

Step-by-step TypeScript 7 migration

Step 1: Upgrade to TypeScript 6.0 first

TypeScript 6.0 shows a deprecation warning for every option that TypeScript 7 removes. Install it and run a type-check:

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

If the list of warnings is long and you need the build green today, you can silence them temporarily. Just remember: TypeScript 7 ignores this escape hatch, because the options are gone for good.

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

Step 2: Fix every deprecation warning

The TypeScript team built a small helper tool that fixes the two most common problems, baseUrl and rootDir, across all your config files (including extends and project references):

# remove baseUrl and rewrite your "paths" entries
npx @andrewbranch/ts5to6 --fixBaseUrl .

# set an explicit rootDir so output folders don't move
npx @andrewbranch/ts5to6 --fixRootDir .

Commit these changes separately, then remove ignoreDeprecations and run npx tsc --noEmit again until it is clean. The next section explains each change by hand, so you understand what the tool did.

Step 3: Install TypeScript 7

npm install -D typescript@7
npx tsc --version
# Version 7.0.x

Nothing else changes in your scripts. tsc, tsc -b, tsc --watch and tsc --noEmit all work as before. If you tried the preview earlier, you can now remove @typescript/native-preview and replace any tsgo commands with tsc.

Step 4: Type-check and fix new errors

Because strict is now true by default, projects that never set it will suddenly see many new errors. Here is a typical example:

interface User {
  name: string;
  email?: string;
}

// Before: worked without strict mode
// After: error TS7006: Parameter 'u' implicitly has an 'any' type.
export function greet(u) {
  return "Hello " + u.name;
}

// Fixed version
export function greetUser(u: User): string {
  return `Hello ${u.name}`;
}

// strictNullChecks: email may be undefined
export function emailDomain(u: User): string {
  return u.email?.split("@")[1] ?? "unknown";
}

If you get hundreds of errors, don’t panic. Set "strict": false explicitly for now, finish the upgrade, and then turn strict checks on one by one (noImplicitAny, then strictNullChecks, and so on) in later pull requests.

Step 5: Update your editor and CI

In VS Code, install the official TypeScript 7 extension from the marketplace so the editor uses the native language server (Visual Studio turns it on automatically). Other editors, such as WebStorm, can use it through the Language Server Protocol. Finally, check your CI pipeline. If you followed our guide on GitHub Actions CI/CD for Node.js, your npm run typecheck step needs no change. It just finishes much sooner.

tsconfig changes you must make for TypeScript 7

This is the part of the migration where most people get stuck. The table below lists what changed. After it, we go through the most common fixes with before-and-after examples.

Fix 1: Replace baseUrl with full paths

Many projects used baseUrl only to make paths work. Since TypeScript 4.1, paths works without it, so simply move the folder prefix into each mapping:

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

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

If your code also used bare imports like import x from "utils/date" (which worked because of baseUrl), add a catch-all mapping: "*": ["./src/*"].

Fix 2: List your global types

Because types now defaults to an empty list, TypeScript no longer loads every @types package in node_modules. That makes builds faster, but you will see errors like Cannot find name 'process' or Cannot find name 'describe'. Fix them by naming the packages you actually use:

{
  "compilerOptions": {
    "types": ["node", "jest"]
  }
}

Fix 3: Set rootDir when you emit JavaScript

If you compile src/index.ts to dist/ and suddenly your output appears at dist/src/index.js, it is because rootDir now defaults to the folder containing tsconfig.json. Make it explicit:

{
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist"
  },
  "include": ["./src"]
}

Fix 4: Compiling a single file

Running tsc hello.ts inside a folder that has a tsconfig.json now stops with error TS5112, because it is unclear which settings you want. Add the new flag to skip the config file on purpose:

npx tsc --ignoreConfig hello.ts

Recommended TypeScript 7 config by project type

Pick your project type below to see a clean, TypeScript 7-ready tsconfig.json and the notes that matter for it.

{
  "compilerOptions": {
    "target": "es2023",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "rootDir": "./src",
    "outDir": "./dist",
    "types": ["node"],
    "strict": true,
    "skipLibCheck": true,
    "sourceMap": true
  },
  "include": ["./src"]
}

{
  "compilerOptions": {
    "target": "es2022",
    "lib": ["es2022", "dom", "dom.iterable"],
    "module": "esnext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "types": ["vite/client"],
    "noEmit": true,
    "strict": true,
    "skipLibCheck": true,
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["src"]
}

npm install -D typescript@^7
npx next build

{
  "compilerOptions": {
    "target": "es2022",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "rootDir": "./src",
    "outDir": "./dist",
    "declaration": true,
    "declarationMap": true,
    "types": [],
    "strict": true
  },
  "include": ["./src"]
}

Running TypeScript 6 and 7 side by side

TypeScript 7.0 ships without a stable programmatic API. The team has said a new (and different) API is planned for TypeScript 7.1. Until then, tools that import "typescript" in JavaScript, such as typescript-eslint, vue-tsc, Svelte and Astro checkers, or Angular’s compiler, still need TypeScript 6.

The official answer is a compatibility package called @typescript/typescript6. It contains TypeScript 6 but names its command tsc6, so it does not clash with TypeScript 7’s tsc. Using npm aliases, you give the name typescript to version 6 (for tools) and install version 7 under another name (for fast checking):

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "lint": "eslint ."
  },
  "devDependencies": {
    "@typescript/native": "npm:typescript@^7.0.2",
    "typescript": "npm:@typescript/typescript6@^6.0.2"
  }
}

Now npm run typecheck uses the fast TypeScript 7 tsc, while ESLint (and any other tool that imports typescript) quietly gets the TypeScript 6 API. When 7.1 lands and your tools support it, delete the alias and install plain typescript again.

New TypeScript 7 flags: checkers, builders and single-threaded mode

TypeScript 7 adds three command-line flags to control how much parallel work it does:

# use 8 type-checking workers (faster on big machines, uses more memory)
npx tsc --noEmit --checkers 8

# monorepo with project references: build up to 4 projects at once
npx tsc -b --builders 4

# turn off all parallel work (useful for debugging or tiny CI runners)
npx tsc --noEmit --singleThreaded

For most people the defaults are fine. Consider lowering --checkers on small CI machines with 2 CPU cores and limited RAM, and raising it on a powerful laptop or build server. Measure with a simple timer before and after:

time npx tsc --noEmit
time npx tsc --noEmit --checkers 8

The rebuilt --watch mode is another quiet win. It now uses a Go port of the Parcel file watcher, which the team says is more stable and uses fewer resources than the old Node.js-based watcher.

Common TypeScript 7 errors and fixes

These are the problems developers hit most often during the upgrade, with the quickest fix for each.

TypeScript 7 best practices

Here is a handy script set for a typical project after the upgrade:

{
  "scripts": {
    "dev": "vite",
    "build": "npm run typecheck && vite build",
    "typecheck": "tsc --noEmit",
    "typecheck:watch": "tsc --noEmit --watch",
    "typecheck:ci": "tsc --noEmit --checkers 2"
  }
}

Frequently Asked Questions

Conclusion

TypeScript 7 is the biggest change to the TypeScript toolchain since the language was created, yet for your day-to-day code it feels familiar. The real work in the migration is cleaning up your tsconfig.json: remove baseUrl, list your types, set rootDir, move off es5 and old module settings, and decide how to handle strict. Do that on TypeScript 6 first, switch to 7 in a small follow-up change, and use the TypeScript 6 compatibility package for any tool that still needs the old API.

The reward is a compiler and editor that are roughly ten times faster, which means shorter CI runs, quicker feedback and less waiting. For every detail, read the official TypeScript 7.0 announcement and the TypeScript 6.0 release notes, which explain each deprecated option.