TypeScript 7 Migration Guide: tsgo, Breaking Changes, Build Times

TypeScript 7.0 Beta is out. The compiler is rewritten in Go, and the numbers are real: VS Code's 1.5M-line codebase goes from 78 seconds to 7.5 seconds. Sentry's monorepo drops from 133 seconds to 16.

We covered the original announcement in our post on TypeScript 7 (Project Corsa) and what it means for Next.js projects. This guide is the sequel for developers already running TypeScript 5.x or 6.x: what do you actually need to do to move your existing project to TypeScript 7, what breaks, and is it worth doing today?

The headline change is simple: the compiler was ported from TypeScript (running on Node.js) to Go. That's it. It is not a new type system, not a new syntax, not a new set of compiler options.

Type-checking semantics, error messages, and behavior on both valid and invalid code are structurally identical to TypeScript 6. If your code compiles cleanly under TS6, it will compile the same way under TS7 (with a small set of exceptions covered below).

What changed is execution, not behavior:

The new binary is tsgo. The legacy tsc binary still works through an interop shim, so existing scripts won't break overnight. But tsc is now a compatibility layer, not the primary implementation: future performance work goes into tsgo, not tsc.

These are measured numbers from real codebases, not synthetic micro-benchmarks:

Notice the pattern: the speedup gets bigger as the project gets bigger. That's expected, parallelism gains are most pronounced at scale, where there are more independent files and packages to spread across cores.

Smaller projects still benefit, just less dramatically. A 20k-line app going from 3.2s to 1.1s is a real improvement to editor responsiveness and incremental builds, even if it doesn't make headlines.

The stable typescript@7.0.0 npm package isn't out yet, it's expected late June or early July 2026. But the native preview package is functionally equivalent for most projects, and you can run it side by side with your existing setup right now.

TypeScript 7 has 99%+ feature parity with TypeScript 6. But a handful of legacy patterns that were already deprecated are now fully gone. Here's the complete list.

The assert keyword for import attributes has been deprecated since TypeScript 5.3 and is now mandatory to replace. Use with instead of assert.

This only affects .js files that use JSDoc-based types, not .ts or .tsx files. If you were relying on @enum to get enum-like behavior in plain JavaScript, replace it with a @typedef over a typeof key-union.

Reassigning MyClass.prototype to an object literal used to get special-cased type inference in the old compiler. tsgo doesn't replicate that special case. This pattern is rare in modern codebases, but if you have it, refactor to a proper class body or object literal.

Some older code captures this into a variable (const self = this;) to work around callback scoping issues from before arrow functions were common. tsgo may type these patterns slightly differently than tsc did.

This is less common than the other three changes, since arrow functions have made this aliasing largely unnecessary for years. If tsgo --noEmit flags one of these, the fix is almost always replacing the callback with an arrow function.

A few deprecated compiler options are removed entirely in TypeScript 7, not just deprecated.

To find every removed option in your config before you upgrade, run tsgo against your project and grep for the removal warning:

If you'd rather start clean, the TSConfigBuilder tool generates a tsconfig.json that's compatible with TypeScript 7 defaults from the ground up, useful for new projects or as a reference when auditing an existing config.

Monorepos are where tsgo's parallel type-checking shows up most. Independent packages get checked simultaneously across CPU cores instead of one after another, sometimes more than 10x faster on the parallel portion of the build.

Project references (the references: [] array in tsconfig.json) and --incremental work the same way they did in TypeScript 6. The relative gain from --incremental is smaller under TS7 though, since the non-incremental baseline is already so much faster that there's less room left to save.

The mechanical change is swapping tsc --noEmit for tsgo --noEmit in your type-check step. You don't have to do this as a single cutover.

Running both side by side lets you treat tsgo errors as warnings during migration. Once the two steps consistently agree, drop the tsc step and remove continue-on-error from the tsgo step.

If you're setting up GitHub Actions for type checking for the first time, our GitHub Actions tutorial covers general workflow setup, triggers, and caching.

Microsoft describes the Beta as "highly stable, highly compatible, and ready to be put to the test in your daily workflows and CI pipelines today."

Greenfield projects and teams comfortable running a beta compiler have no real reason to wait. Everyone else can run tsgo --noEmit alongside their existing setup this week and know within minutes whether the migration is trivial or needs cleanup first.