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.

Before you touch a single line of CI config, spend twenty minutes auditing what you are actually migrating. Most stalled migrations stall because nobody checked the dependency surface first, not because the compiler misbehaved.

Work through this list and write the answers down. Anything you cannot answer confidently is a task, not a blocker.

A migration you can stop at any point is worth more than a fast one you cannot. Each stage below is independently useful, independently revertible, and leaves the repository in a working state.

On a small app you might run all five stages in an afternoon. On a large monorepo, budget roughly a week per stage and let each one soak in CI before moving on.

Published benchmark numbers tell you the shape of the improvement, not your number. Project structure, dependency graph depth, and available core count all move the result, sometimes by a factor of three.

Measuring it properly takes about ten minutes and gives you something concrete to put in the migration proposal instead of someone else's screenshot.

Run every measurement from the same machine, on the same branch, against the same tsconfig.json. Clear incremental build state first, because a warm .tsbuildinfo file makes the second run of either compiler look artificially fast.

Keep the fastest of the three runs, not the average. The fastest run is the one least polluted by background processes on your machine, and it is the number most likely to reproduce on someone else's.

Run the identical loop with tsgo, then record both numbers alongside the details that explain them. A bare speedup figure is unusable six months later when someone asks why you migrated.

The CI number is the one that surprises people. CI runners often have more cores but slower single-thread performance than a developer laptop, so a parallel compiler tends to look better in CI than it does on your desk.

Watch the ratio between the cold and warm numbers too. If your warm incremental check was already fast, the migration mostly buys you cheaper cold checks, which is a CI win rather than a local-development win. That distinction changes who on the team notices the difference.

This is the most common reason a migration stalls, and it is almost never the compiler's fault. The distinction that decides how hard a given tool is to migrate is how that tool consumes TypeScript.

Tools that shell out to a binary (npm scripts, CI steps, Makefiles) are trivial to point somewhere else. Tools that import the typescript package and call into it programmatically are the ones that break, because they depend on an API surface rather than a command line.

For the blocked category, the answer is neither to wait idly nor to force the install. Keep two compilers installed and give each one a job it can actually do: the existing typescript package stays for anything that imports it as a library, and the native preview handles command line type-checking only.

Forcing an install past a peer dependency conflict is the failure mode to avoid. It does not fix the incompatibility, it just moves the error from install time to run time, where the stack trace points into someone else's internals instead of your config. If you are already staring at an ERESOLVE wall of text, the ERESOLVE Explainer will name the two packages that actually disagree.

For each blocked dependency, work out which of three buckets it falls into before you spend any engineering time on it.

One thing worth checking before you assume a tool is blocked: does anything in your pipeline actually depend on it for correctness, or is it there out of habit? Teams regularly find a type-aware plugin in their build that nothing reads the output of. Deleting it is faster than migrating it.

A faster compiler makes the rest of your pipeline's overhead visible. When type checking drops from ninety seconds to eight, a forty second dependency install stops being background noise and becomes the next thing worth fixing.

The native preview ships a platform-specific native binary, which changes what is safe to cache. Caching your package manager's download store, keyed on the lockfile, is safe and effective. Caching an entire installed node_modules directory across jobs that run on different operating systems or CPU architectures is not, because you can restore a binary built for the wrong platform.

npm ci plus a package manager cache is the right default. It respects the lockfile exactly, and the cache key changes automatically when the lockfile changes, so you never restore a stale binary next to a new lockfile.

If your project uses incremental builds, the .tsbuildinfo file is worth caching separately, keyed on a hash of your source tree. Just be aware that the payoff is smaller than it used to be: the non-incremental baseline is now fast enough that restoring and validating a cache can cost more than it saves on smaller projects. Measure before you add it.

Put the type check early in the pipeline, ahead of the bundle build and the test suite. It is now the cheapest meaningful signal you have, and an error that surfaces in eight seconds costs a developer almost nothing compared to one that surfaces after a four minute build.

Resist the urge to split the type check into its own parallel job purely to make the pipeline graph look tidy. A separate job pays container startup and dependency install costs all over again, and on most pipelines that overhead is now larger than the type check itself.

The reason this migration is low risk is that there is very little state to unwind. You are not rewriting source code, not changing your type system, and not changing what your build emits. You are swapping which binary reads the same tsconfig.json.

That means rollback is a config change, and it should be one you can land in a single small pull request at any stage of the rollout.

Two habits make all of this cheap. First, keep each stage of the rollout in its own commit, so reverting one stage never drags another along with it. Second, never combine the compiler swap with an unrelated tsconfig.json cleanup in the same pull request. If you change two things and the build goes red, you have doubled your debugging surface for no benefit.

On a codebase with one or two contributors, the technical plan is the whole plan. On a codebase with thirty, sequencing matters more than the commands do.

The failure mode is not a broken build. It is five people independently discovering the same new error on their branches on the same afternoon, and each spending an hour on it separately.

Keep the announcement short and answer the three questions people will genuinely have.

Time the flip in stage 3 for the start of a week, not a Friday afternoon and not the day before a release freeze. The change is low risk, but low risk is not zero risk, and you want the migration owner online when it lands.

On a large monorepo, sequence by blast radius rather than by size. A leaf package with no dependents is a better first candidate than the shared types package everything imports, even though the shared package would show the bigger speedup. Get the process right somewhere low stakes, then apply it where it pays.

Finally, write down the numbers you measured and the date you flipped each stage. When the stable release lands and someone asks whether it is worth upgrading the rest of the organisation, that short record is the entire business case, already written.

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.