Status as of this writing (July 2026): TypeScript 7.0 is stable / generally available.It shipped as a Release Candidate on June 18, 2026, and Microsoft has now published the full "Announcing TypeScript 7.0" stable release. This guide reflects thestablerelease, not the RC. If you're reading this much later, sanity-check version numbers against[https://devblogs.microsoft.com/typescript/]before running anything.
This doc is written so an AI coding agent (or a human) can follow it step-by-step to migrate a repo from TypeScript 6.x to TypeScript 7.0. Copy the "Agent Instructions" block at the bottom into your prompt if you want an agent to execute this unattended.
- The compiler and language service were ported from the old self-hosted
TypeScript-in-TypeScript codebase ("Strada") to a
native Go codebase("Project Corsa"). This was a** port**, not a redesign — the type-checking algorithms and semantics are intentionally kept structurally identical to TypeScript 6.0. - Microsoft's own benchmark: the ~1.5M-line VS Code codebase went from ~78s to ~7.5s for a full type-check (~10x). Editor project load and language-server responsiveness improved similarly, with fewer language-server crashes.
The package name and binary did not change for the stable release. You install
typescript
from npm exactly like before, and you still runtsc
. There is no separatetsgo
binary in the stable release —tsgo
only exists in the nightly preview package (@typescript/native-preview
), which is unrelated infrastructure the team keeps around for testing bleeding-edge builds ahead of the next TypeScript version.No stable programmatic API yet. Tools thatimport * as ts from "typescript"
and call into the compiler API (typescript-eslint, ts-morph, custom transformers, some bundler plugins) are not guaranteed to work against the Go compiler. A stable new API is targeted forTypeScript 7.1, not 7.0.- TypeScript 7.0 inherits all of TypeScript 6.0's new defaults and turns everything that was merely deprecated in 6.0 into ahard error in 7.0. This is the part that actually breaks projects — see section 3.
npm install -D typescript@latest
npm install -D typescript@7.0.0
Run it exactly as before:
npx tsc --noEmit
npx tsc --build
Because the compiler API isn't stable yet, tools like typescript-eslint
may
still expect a TypeScript 6.x API. Microsoft publishes a compatibility package,
@typescript/typescript6
, that re-exports the 6.0 API and ships a tsc6
binary so you can run both side by side without a naming collision:
// package.json
{
"devDependencies": {
// "typescript" stays on 6.x so linting/tooling that imports the API keeps working
"typescript": "npm:@typescript/typescript6@^6.0.0",
// alias the real TypeScript 7 compiler under a different name
"typescript-7": "npm:typescript@^7.0.0"
}
}
With this setup: npx tsc
(via the typescript
alias) still gives tools the
6.0 API, tsc6
is also available explicitly, and you invoke the Go compiler
for your actual build/type-check step via npx --package typescript-7 tsc
(or add an npm script that points at node_modules/typescript-7/bin/tsc
).
Drop this alias entirely once your tooling (ESLint, ts-morph, custom transformers) confirms compatibility with TypeScript 7.1+'s stable API.
If you specifically want to track unreleased nightly builds ahead of the next TypeScript version, that's a separate package with its own binary name:
npm install -D @typescript/native-preview
npx tsgo --noEmit
Don't use this for a normal 7.0 migration — it's for previewing what comes
after 7.0. The stable typescript
package is what you want.
These were deprecated in TypeScript 6.0 and are hard errors in 7.0. If you haven't already upgraded to 6.0 and cleared its deprecation warnings, do that first — it's a much smaller, reversible step, and it tells you exactly what 7.0 will reject.
| Old / deprecated | Status in 7.0 | Fix |
|---|---|---|
target: "es5" |
||
| Hard error | Set target to es2022 or later (or esnext ) |
|
downlevelIteration |
||
| No longer meaningful | Remove it | |
moduleResolution: "node" / "node10" |
||
| Hard error | Use "nodenext" (Node projects) or "bundler" (bundler/Vite/webpack projects) |
|
moduleResolution: "classic" |
||
| Hard error | Use "nodenext" or "bundler" |
|
| `module: "amd" | "umd" | "system" |
| Hard error | Use "esnext" (with a bundler) or "preserve" |
|
baseUrl |
||
| Hard error | Remove it; rewrite paths entries to be relative to the tsconfig directory instead of relative to baseUrl |
|
esModuleInterop: false |
||
| Hard error | Remove the false (interop is always on) |
|
allowSyntheticDefaultImports: false |
||
| Hard error | Remove the false |
|
outFile (non-AMD/System) |
||
| Hard error in most configs | Use per-module output / a bundler | |
ignoreDeprecations: "6.0" |
||
| Does not work in 7.0 | ||
| This was only ever a 6.0 escape hatch — you must actually fix the underlying options |
| Option | Old default | New default (7.0) | What to do |
|---|---|---|---|
strict |
|||
false |
|||
true |
|||
Either embrace it and fix the resulting errors, or set "strict": false explicitly to opt out |
|||
target |
|||
| (varied / es5-ish) | latest stable ECMAScript (e.g. es2025 ) |
||
| Set explicitly if you need a specific target | |||
module |
|||
| (varied) | esnext |
||
Set explicitly if you need commonjs /nodenext /preserve |
|||
rootDir |
|||
| inferred from input files | current directory (./ ) containing tsconfig.json |
||
Set "rootDir": "./src" explicitly if your sources live in a subfolder — otherwise output nests as dist/src/... instead of dist/... |
|||
types |
|||
auto-discovered from node_modules/@types |
|||
[] (nothing auto-included) |
|||
Set "types": ["node", "jest", ...] explicitly for every @types package you rely on globally |
|||
stableTypeOrdering |
|||
| opt-in | always on, cannot be disabled | No action needed unless you had disabled it; declaration emit ordering may shift slightly |
// BEFORE — relies on inference, silently breaks output layout in 7.0
{
"compilerOptions": {
"outDir": "./dist"
},
"include": ["src"]
}
// AFTER — explicit rootDir keeps dist/index.js instead of dist/src/index.js
{
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src",
"types": ["node"]
},
"include": ["src"]
}
// BEFORE — baseUrl-relative paths (hard error in 7.0)
{
"compilerOptions": {
"baseUrl": "./src",
"paths": { "@app/*": ["app/*"] }
}
}
// AFTER — paths relative to the tsconfig.json location, no baseUrl
{
"compilerOptions": {
"paths": { "@app/*": ["./src/app/*"] }
}
}
// BEFORE — legacy resolution
{ "compilerOptions": { "module": "commonjs", "moduleResolution": "node" } }
// AFTER — pick one based on your setup
// Node.js project without a bundler:
{ "compilerOptions": { "module": "nodenext", "moduleResolution": "nodenext" } }
// Project using Vite/webpack/esbuild/Bun:
{ "compilerOptions": { "module": "esnext", "moduleResolution": "bundler" } }
TypeScript 7.0 parallelizes parsing, type-checking, and emit across worker threads/processes. Parsing and emit parallelize almost for free; type-checking uses a fixed pool of workers because files share type information.
tsc --checkers 8
tsc --build --builders 4
tsc --singleThreaded
Guidance: more --checkers
helps on large codebases with many CPU cores, but returns diminish and memory use grows — measure on your own repo rather than maxing it out blindly.
--watch
was also rebuilt on a new cross-platform file-watching foundation
(ported from Parcel's watcher) instead of polling, so cold start and rebuild
latency both drop noticeably, especially in large node_modules
trees.
No stable compiler/programmatic API.typescript-eslint
,ts-morph
, custom AST transformers, and codegen pipelines thatimport
the compiler should keep using the TypeScript 6.0 API (via@typescript/typescript6
) until TypeScript 7.1 ships a stable API.- Declaration map generation and a few advanced
--build
/ project-reference edge cases may have rough edges relative to 6.0 — check your specific setup before flipping CI over unconditionally. - JavaScript/JSDoc type-checking was rewritten and is stricter/simpler; a
handful of previously-recognized JSDoc patterns (e.g. certain
@enum
/@constructor
tag usages) are no longer specially recognized. - Editor/IDE plugins that hook into the old compiler API (some VS Code extensions, JetBrains plugins) may lag behind until they update for the new architecture.
Baseline on TypeScript 6.0 first, if you haven't already. Fix every deprecation warning it emits — do** not**useignoreDeprecations: "6.0"
as a permanent fix, since it stops working entirely in 7.0.Delete stale build artifacts..tsbuildinfo
incremental-build files from the old JS compiler are not compatible with the Go compiler's incremental format.
find . -name "*.tsbuildinfo" -not -path "*/node_modules/*" -delete
Install TypeScript 7.0(npm install -D typescript@latest
), keeping the@typescript/typescript6
alias in place for anything that imports the compiler API directly (see section 2).Update per the table in section 3: remove removed/deprecated options, settsconfig.json
rootDir
andtypes
explicitly, choosemoduleResolution
/module
deliberately instead of relying on defaults.Run a full type-check and compare diagnostics against your last known good TypeScript 6.0 run:Any new errors should map cleanly to the table in section 3 (strict mode, moved defaults) — if you see something unexplained, check section 5's known-gaps list before assuming it's a real regression.
npx tsc --noEmit > ts7-output.txt 2>&1
diff ts6-baseline-output.txt ts7-output.txt
Update build scripts and CI to run the sametsc
command as always — no script changes should be needed beyond new flags you opt into (--checkers
,--builders
,--singleThreaded
).Update editor tooling. If you were using the "TypeScript Native Preview" VS Code extension during beta/RC, switch back to the standard built-in TypeScript support (or make sure it's pointed at your project's localtypescript
7.0 install) now that this is the standard release.Run both compilers in CI for one transition cycle if you want extra safety: keep a non-blocking job running the old TypeScript 6.0 (tsc6
, if you kept the alias) alongside the new default, and drop it once you're confident.Drop the TypeScript 6.0 alias once your tooling ecosystem (typescript-eslint, ts-morph, custom transformers) confirms support for TypeScript 7.1's stable API.File issues for any genuine compiler regressions athttps://github.com/microsoft/typescript-go/issues(not the mainmicrosoft/TypeScript
repo — that's for language/API-level issues).
{
"compilerOptions": {
"target": "es2022",
"module": "nodenext", // or "esnext" + "moduleResolution": "bundler"
"moduleResolution": "nodenext",
"strict": true,
"types": ["node"],
"rootDir": "./src",
"outDir": "./dist",
"esModuleInterop": true,
"skipLibCheck": true,
"incremental": true
},
"include": ["src"],
"exclude": ["node_modules", "dist"]
}
Migrate this repository from TypeScript 6.x to TypeScript 7.0 following
typescript-7-migration-guide.md in this repo/gist. Specifically:
1. Delete all *.tsbuildinfo files outside node_modules.
2. Run `npx tsc --noEmit` and save the output as a baseline.
3. Update package.json: set "typescript" to "^7.0.0". If any dependency
(typescript-eslint, ts-morph, custom transformer) imports the `typescript`
package's compiler API directly, add it as "typescript": "npm:@typescript/typescript6@^6.0.0"
instead, and add a separate "typescript-7": "npm:typescript@^7.0.0" entry
for the actual build/type-check step.
4. In every tsconfig.json (including base configs used via "extends"):
- Remove baseUrl; rewrite any "paths" entries to be relative to the
tsconfig.json location instead.
- Replace target: "es5" with target: "es2022" (or newer) unless the
project explicitly needs ES5 output, in which case flag this for human review.
- Replace moduleResolution "node"/"node10"/"classic" with "nodenext" if the
project has no bundler, or "bundler" if it uses Vite/webpack/esbuild/Bun.
- Replace module "amd"/"umd"/"system"/"none" with "esnext" or "preserve".
- Remove esModuleInterop: false and allowSyntheticDefaultImports: false
(just delete the false; the behavior is now always on).
- Add explicit "rootDir" pointing at the actual source directory if not present.
- Add explicit "types" array listing every @types package actually used
(check node_modules/@types for what's currently installed and referenced).
- Remove any "ignoreDeprecations" field.
5. Run `npx tsc --noEmit` again and diff against the baseline from step 2.
For every new error, resolve it by referencing the breaking-changes table
in the guide (most will be strict-mode violations from the new
strict: true default — fix them properly, don't silently disable strict
unless told to).
6. Update CI config and npm scripts to keep using `tsc`/` tsc --build` as
before; add `--checkers <N>` only if a human asks for perf tuning.
7. Do not attempt to change custom AST transformers, ts-morph scripts, or
typescript-eslint config to use the new compiler API — leave those on the
6.0 API alias (typescript-7.1 will have a stable API for this later).
8. Summarize every tsconfig.json change and every new type error fixed, and
flag anything you were unsure about instead of guessing silently.