The Go Rewrite Migration Information

TypeScript 7.0 RC marks essentially the most important architectural shift within the compiler’s historical past. All the TypeScript compiler has been rewritten in Go, a venture internally codenamed “Corsa,” delivering as much as roughly 9-10x sooner construct instances throughout real-world codebases relying on venture measurement (see benchmark desk). This migration information walks by the concrete steps wanted to undertake the Go rewrite with out breaking present initiatives, masking set up, configuration adjustments, construct pipeline updates, and the sting circumstances that journey groups up in the course of the transition.

The way to Migrate to TypeScript 7.0 RC (tsgo)

1. Audit your present TypeScript model and all packages that depend upon the compiler API (ts-loader, ts-node, ts-morph, and many others.).
2. Set up the @typescript/native package deal from npm alongside your present typescript package deal, pinned to a precise RC model.
3. Delete all stale .tsbuildinfo recordsdata, because the Go compiler’s incremental artifacts are incompatible with the JS compiler’s.
4. Run tsgo --noEmit towards your venture and evaluate diagnostic codes with tsc output to catch behavioral divergences.
5. Replace tsconfig.json by eradicating preserveConstEnums and noting unported options like declarationMap.
6. Regulate construct scripts and CI pipelines to invoke tsgo for type-checking whereas protecting tsc as a parallel security internet.
7. Configure your editor (VS Code TypeScript Native Preview extension) to make use of the Go-based language service.
8. Validate by working each compilers in CI throughout a transition interval earlier than dropping the legacy tsc dependency.

Desk of Contents

{
  "scripts":  grep -E 'ts-loader
}

The compiler is offered by npm or as a standalone binary obtain. Confirm the precise npm package deal identify and binary obtain URLs on the typescript-go releases web page earlier than putting in, as these might change earlier than steady launch.

VERSION="<exact-version>"  
npm set up --save-dev @typescript/native@"$VERSION"


npx tsgo --version

For the standalone binary, all the time confirm the SHA-256 checksum of downloaded binaries towards the worth printed on the official releases web page earlier than executing them. Don’t run binaries downloaded with out checksum verification.

curl --proto '=https' --tlsv1.2 -fsSL 
  https://typescript.azureedge.internet/releases/7.0.0-rc/tsgo-darwin-arm64 
  -o /usr/native/bin/tsgo


EXPECTED_SHA256="<replace-with-value-from-releases-page>"
ACTUAL_SHA256=$(shasum -a 256 /usr/native/bin/tsgo | awk '{print $1}')

if [ "$ACTUAL_SHA256" != "$EXPECTED_SHA256" ]; then
  echo "ERROR: Checksum mismatch. Anticipated: $EXPECTED_SHA256  Received: $ACTUAL_SHA256" >&2
  rm -f /usr/native/bin/tsgo
  exit 1
fi

chmod +x /usr/native/bin/tsgo
tsgo --version

The standalone binary URL proven is for macOS arm64. Confirm the proper URL on your OS and structure (Linux x86_64, Home windows, and many others.) on the releases web page.

To run alongside an present TypeScript 5.x or 6.x set up, preserve the typescript package deal in devDependencies and add the Go-based package deal individually. Each binaries land in node_modules/.bin, so you may run them aspect by aspect.

Step 2: Operating Your First Construct with tsgo

Level the brand new compiler at an present venture by working tsgo within the venture root. It reads the identical tsconfig.json routinely.

$ npx tsc --diagnostics
Information:            387
Traces:          94521
Nodes:         412893
Whole time:    12.4s


$ npx tsgo --diagnostics
Information:            387
Traces:          94521
Nodes:         412893
Whole time:     1.3s

The diagnostics output format differs barely. Error messages use the identical diagnostic codes however wording differs; diagnostic codes stay an identical, so match on codes, not message textual content. The --diagnostics flag works in each compilers, making side-by-side comparability straightforward.

Step 3: Updating tsconfig.json

Most tsconfig.json recordsdata work with out adjustments. Nevertheless, a couple of choices warrant consideration.

{
  "compilerOptions": {
    // Unchanged — these work identically in 7.0 RC
    "goal": "ES2022",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist",

    // Nonetheless supported however restricted in RC:
    "declarationMap": true, // ⚠️ RC generates .d.ts recordsdata usually however does NOT generate .d.ts.map recordsdata. IDE go-to-definition for library shoppers will probably be affected.

    // Parallel type-checking is on by default; no tsconfig flag is required.
    // See launch notes for future opt-in choices.

    // Take away if current — not acknowledged:
    // "preserveConstEnums" is eliminated. The Go compiler all the time emits const enum
    // declarations in output (equal to the previous preserveConstEnums: true).
    // In case your code relied on const enum *inlining* (the default
    // preserveConstEnums: false habits), take a look at your JS runtime output fastidiously.
  },
  "embrace": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

The strict flag and all its constituent flags (strictNullChecks, strictFunctionTypes, and many others.) behave identically. The Go compiler drops the preserveConstEnums possibility as a result of it all the time emits const enum declarations in output (equal to the previous preserveConstEnums: true). In case your construct relied on const enum inlining throughout module boundaries (the default habits when preserveConstEnums was false), this can be a behavioral change. Take a look at your runtime JS output fastidiously.

Step 4: Adapting Your Construct Pipeline

Tasks utilizing bundlers really feel this variation solely within the type-checking step, not transpilation. Instruments like esbuild, Vite, and SWC deal with their very own transpilation and solely invoke TypeScript for type-checking.

Delete stale incremental artifacts earlier than the primary tsgo run. The Go compiler’s .tsbuildinfo recordsdata are usually not suitable with these from the JS compiler:

discover . 
  -maxdepth 5 
  -name '*.tsbuildinfo' 
  -not -path '*/node_modules/*' 
  -print


discover . 
  -maxdepth 5 
  -name '*.tsbuildinfo' 
  -not -path '*/node_modules/*' 
  -delete

{
  "scripts": {
    "typecheck": "tsgo --noEmit",
    "typecheck:legacy": "tsc --noEmit",
    "typecheck:evaluate": "time npm run typecheck:legacy; time npm run typecheck",
    "construct": "tsgo --noEmit && vite construct",
    "watch": "tsgo --watch --noEmit",
    "lint": "eslint . --ext .ts,.tsx",
    "ci:typecheck": "tsgo --noEmit --diagnostics"
  }
}

The "construct" script above makes use of tsgo --noEmit for type-checking solely earlier than handing off to Vite for transpilation and bundling. Omit --noEmit provided that you plan tsgo to emit JS output instantly. The "typecheck:evaluate" script makes use of ; as an alternative of && in order that tsgo timing runs even when tsc exits non-zero on account of sort errors.

CI/CD pipelines profit as a result of the native binary eliminates the Node.js runtime dependency for type-checking. CI pictures can shrink provided that you employ the standalone binary and no different Node.js tooling stays required. The binary should match the CI runner’s OS and structure. Cache the tsgo binary alongside node_modules, and delete any stale .tsbuildinfo recordsdata when switching compilers, because the Go compiler’s incremental artifacts are incompatible with these from the JS compiler.

ts-loader customers: the loader’s transpileOnly: true mode continues to work because it bypasses type-checking totally. ts-loader’s full type-check mode calls the JS compiler API, which tsgo doesn’t expose. Confirm compatibility together with your particular ts-loader model.

Step 5: Updating Editor and IDE Configuration

In VS Code, the TypeScript group offers an up to date extension that makes use of the Go-based language service. Seek for the TypeScript Native Preview extension on the VS Code Market (confirm the present extension identify, as it could differ between releases), then configure your .vscode/settings.json:

{
  "typescript.tsserver.useTsgo": true
}

Confirm this setting key towards the extension’s README; it could differ between extension variations. If VS Code exhibits a yellow warning on the setting or the important thing doesn’t seem within the Settings UI search, seek the advice of the extension documentation for the proper configuration.

JetBrains IDEs (WebStorm, IntelliJ IDEA) don’t but supply native tsgo language service integration as of the RC. These IDEs proceed to make use of the JavaScript-based language service. Groups utilizing JetBrains can nonetheless run tsgo for command-line type-checking whereas counting on the bundled TypeScript service for editor options.

To report discrepancies, the TypeScript group tracks behavioral variations on the microsoft/typescript-go GitHub repository. Seek for points tagged with divergence-related labels (confirm present label names on the repository). Operating each compilers in parallel throughout a validation interval is strongly advisable. A easy CI step can implement this:

npx tsc --noEmit 2> legacy-errors.txt
npx tsgo --noEmit 2> native-errors.txt


diff 
  <(grep -oE 'TS[0-9]+' legacy-errors.txt | kind | uniq -c | kind -k2) 
  <(grep -oE 'TS[0-9]+' native-errors.txt  | kind | uniq -c | kind -k2)

Programmatic API Migration

The TypeScript Compiler API (ts.createProgram, ts.createSourceFile, ts.forEachChild, and many others.) doesn’t exist within the Go rewrite. Instruments constructed on this API, together with ts-morph, customized AST transformers, and code technology pipelines, can’t use tsgo as a drop-in alternative.

The TypeScript group has outlined plans for a language service protocol that exterior instruments can talk with over IPC, however the group has not finalized this protocol within the RC. For now, initiatives counting on the programmatic API ought to proceed utilizing the JavaScript-based typescript package deal for these particular duties whereas utilizing tsgo for build-time type-checking.

The TypeScript Compiler API (ts.createProgram, ts.createSourceFile, ts.forEachChild, and many others.) doesn’t exist within the Go rewrite. Instruments constructed on this API, together with ts-morph, customized AST transformers, and code technology pipelines, can’t use tsgo as a drop-in alternative.

import * as ts from "typescript";

const program = ts.createProgram(["src/index.ts"], { strict: true });


const configDiagnostics = program.getConfigFileParsingDiagnostics();
if (configDiagnostics.size > 0) {
  configDiagnostics.forEach(d =>
    console.error("Config error:", ts.flattenDiagnosticMessageText(d.messageText, "
"))
  );
  course of.exitCode = 1;
} else {
  const diagnostics = ts.getPreEmitDiagnostics(program);
  console.log(diagnostics.size, "errors discovered");
}

import { spawnSync } from "child_process";


const TS_ERROR_PATTERN = /error TSd+:/g;
const MAX_OUTPUT_BYTES = 10 * 1024 * 1024; 

const proc = spawnSync(
  "tsgo",
  ["--noEmit", "--pretty", "false"],   
  {
    encoding: "utf-8",
    maxBuffer: MAX_OUTPUT_BYTES,
    shell: false,                       
  }
);

if (proc.error) {
  throw new Error(`Did not spawn tsgo: ${proc.error.message}`);
}


const output = (proc.stdout ?? "") + (proc.stderr ?? "");
const errorCount = (output.match(TS_ERROR_PATTERN) ?? []).size;
console.log(errorCount, "errors discovered");


if (proc.standing !== 0 && errorCount === 0) {
  console.error("tsgo exited with standing", proc.standing, "— attainable compiler crash");
  course of.exitCode = proc.standing ?? 1;
}

Confirm that tsgo helps the --pretty false flag by checking tsgo --help. stdout and stderr are captured individually to keep away from conflating compiler diagnostics with runtime errors.

• Audit present TypeScript model and all dependent packages
• Evaluation recognized RC limitations towards venture function utilization (declaration maps, --build mode, venture references)
• Confirm the proper npm package deal identify and model on the typescript-go releases web page

Section 2: Set up and Configuration

• Set up TypeScript 7.0 RC alongside present model, pinned to a particular model
• Delete stale .tsbuildinfo recordsdata earlier than the primary tsgo run
• Run tsgo --noEmit towards venture and evaluate diagnostic output with tsc
• Replace tsconfig.json for eliminated choices (preserveConstEnums) and unported options (declarationMap)

Section 3: Construct Pipeline and Tooling

• Regulate construct scripts and CI/CD pipelines to make use of tsgo
• Cache native binary in CI and guarantee OS/structure match
• Replace VS Code settings for native language service (confirm setting key towards extension documentation)
• Validate all programmatic API utilization and migrate to subprocess invocation or retain JS compiler for these paths

Section 4: Validation and Rollout

• Run full take a look at suite and evaluate outcomes between each compilers
• Benchmark construct instances with --diagnostics and doc enhancements
• Arrange parallel compiler runs in CI for validation interval
• Plan timeline for dropping legacy tsc dependency after steady launch

Migrating from the JavaScript-based TypeScript compiler to the Go-based tsgo requires fewer than 5 configuration adjustments for initiatives that use TypeScript for type-checking and emit with out counting on the programmatic API. Confirm the present package deal identify on the typescript-go releases web page, set up it, run tsgo alongside tsc, evaluate diagnostics, replace configurations, and regulate construct pipelines. The programmatic API hole is essentially the most important blocker for tool-heavy initiatives.

The official TypeScript 7.0 RC launch notes and migration documentation can be found on the TypeScript weblog and the microsoft/typescript-go GitHub repository. Take a look at in non-production environments and report divergences by the repository’s concern tracker to assist the group attain a steady launch.