TypeScript 7.0 RC: The Go Rewrite Migration Guide

Pre-Migration Assessment

Checking Your Current Setup

Before migrating, catalog your exact TypeScript version, all packages that depend on it, and whether any tooling calls the TypeScript Compiler API programmatically. Dependencies like ts-loader, ts-node, ts-jest, and @typescript-eslint/parser each interact with TypeScript differently, and their compatibility with 7.0 RC varies.

{
  "scripts": {
    "audit:ts-deps": "npm ls typescript && npm ls | grep -E 'ts-loader|ts-node|ts-jest|typescript-eslint|ts-morph|ttypescript'"
  }
}

For npm v7+, add --depth=Inf if needed: npm ls --depth=Inf typescript. Output format changed between npm v6 and v7+. Running npm run audit:ts-deps surfaces every package in the dependency tree that directly or transitively depends on TypeScript, giving you a clear inventory of what needs verification.

Known Limitations in the RC

The RC does not yet support declaration map generation (--declarationMap). Complex composite project configurations with circular references may produce different behavior in project references. The --build mode (tsc -b) has gaps in multi-project orchestration scenarios. The plugin ecosystem that relied on the JavaScript-based compiler API has no direct equivalent. Editor integration through the language service works in VS Code via an updated extension, but JetBrains has not announced a tsgo integration date as of mid-2025.

Step-by-Step Migration Guide

Step 1: Installing TypeScript 7.0 RC

The compiler is available through npm or as a standalone binary download. Verify the exact npm package name and binary download URLs at the typescript-go releases page before installing, as these may change before stable release.

# Install via npm (adds tsgo binary to node_modules/.bin)
# ⚠️ Verify the package name at https://github.com/microsoft/typescript-go/releases before running.
# Pin to a specific version for reproducible installs.
# Replace with the version from the releases page (e.g., 7.0.0-rc.1):
VERSION=" "  # ⚠️ You MUST replace this placeholder before running
npm install --save-dev @typescript/native@"$VERSION"

# Verify installation
npx tsgo --version

For the standalone binary, always verify the SHA-256 checksum of downloaded binaries against the value published on the official releases page before executing them. Do not run binaries downloaded without checksum verification.

# Standalone binary (macOS arm64 example - check the releases page for your OS/architecture)
curl --proto '=https' --tlsv1.2 -fsSL \
  https://typescript.azureedge.net/releases/7.0.0-rc/tsgo-darwin-arm64 \
  -o /usr/local/bin/tsgo

# Verify checksum - abort if mismatch (replace EXPECTED_SHA256 with value from releases page)
EXPECTED_SHA256=" "
ACTUAL_SHA256=$(shasum -a 256 /usr/local/bin/tsgo | awk '{print $1}')
if [ "$ACTUAL_SHA256" != "$EXPECTED_SHA256" ]; then
  echo "ERROR: Checksum mismatch. Expected: $EXPECTED_SHA256 Got: $ACTUAL_SHA256" >&2
  rm -f /usr/local/bin/tsgo
  exit 1
fi
chmod +x /usr/local/bin/tsgo
tsgo --version

The standalone binary URL shown is for macOS arm64. Verify the correct URL for your OS and architecture (Linux x86_64, Windows, etc.) on the releases page.

To run alongside an existing TypeScript 5.x or 6.x installation, keep the typescript package in devDependencies and add the Go-based package separately. Both binaries land in node_modules/.bin, so you can run them side by side.

Step 2: Running Your First Build with tsgo

Point the new compiler at an existing project by running tsgo in the project root. It reads the same tsconfig.json automatically.

# Old compiler
$ npx tsc --diagnostics
Files:             387
Lines:           94521
Nodes:          412893
Total time:      12.4s

# New compiler, same project
$ npx tsgo --diagnostics
Files:             387
Lines:           94521
Nodes:          412893
Total time:       1.3s

The diagnostics output format differs slightly. Error messages use the same diagnostic codes but wording differs; diagnostic codes remain identical, so match on codes, not message text. The --diagnostics flag works in both compilers, making side-by-side comparison easy.

Step 3: Updating tsconfig.json

Most tsconfig.json files work without changes. However, a few options warrant attention.

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

    // Still supported but limited in RC:
    "declarationMap": true, // ⚠️ RC generates .d.ts files normally but does NOT generate .d.ts.map files. IDE go-to-definition for library consumers will be affected.

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

    // Remove if present - no longer recognized:
    // "preserveConstEnums" is removed. The Go compiler always emits const enum
    // declarations in output (equivalent to the old preserveConstEnums: true).
    // If your code relied on const enum *inlining* (the default
    // preserveConstEnums: false behavior), test your JS runtime output carefully.
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

The strict flag and all its constituent flags (strictNullChecks, strictFunctionTypes, etc.) behave identically. The Go compiler drops the preserveConstEnums option because it always emits const enum declarations in output (equivalent to the old preserveConstEnums: true). If your build relied on const enum inlining across module boundaries (the default behavior when preserveConstEnums was false), this is a behavioral change. Test your runtime JS output carefully.

Step 4: Adapting Your Build Pipeline

Projects using bundlers feel this change only in the type-checking step, not transpilation. Tools like esbuild, Vite, and SWC handle their own transpilation and only invoke TypeScript for type-checking.

Delete stale incremental artifacts before the first tsgo run. The Go compiler's .tsbuildinfo files are not compatible with those from the JS compiler:

# Preview first (dry run - review the list before deleting)
find . \
  -maxdepth 5 \
  -name '*.tsbuildinfo' \
  -not -path '*/node_modules/*' \
  -print

# Execute only after confirming output above is correct
find . \
  -maxdepth 5 \
  -name '*.tsbuildinfo' \
  -not -path '*/node_modules/*' \
  -delete

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

The "build" script above uses tsgo --noEmit for type-checking only before handing off to Vite for transpilation and bundling. Omit --noEmit only if you intend tsgo to emit JS output directly. The "typecheck:compare" script uses ; instead of && so that tsgo timing runs even if tsc exits non-zero due to type errors.

CI/CD pipelines benefit because the native binary eliminates the Node.js runtime dependency for type-checking. CI images can shrink only if you use the standalone binary and no other Node.js tooling remains required. The binary must match the CI runner's OS and architecture. Cache the tsgo binary alongside node_modules, and delete any stale .tsbuildinfo files when switching compilers, since the Go compiler's incremental artifacts are incompatible with those from the JS compiler.

ts-loader users: the loader's transpileOnly: true mode continues to work since it bypasses type-checking entirely. ts-loader's full type-check mode calls the JS compiler API, which tsgo does not expose. Verify compatibility with your specific ts-loader version.

Step 5: Updating Editor and IDE Configuration

In VS Code, the TypeScript team provides an updated extension that uses the Go-based language service. Search for the TypeScript Native Preview extension on the VS Code Marketplace (verify the current extension name, as it may differ between releases), then configure your .vscode/settings.json:

{
  "typescript.tsserver.useTsgo": true
}

Verify this setting key against the extension's README; it may differ between extension versions. If VS Code shows a yellow warning on the setting or the key does not appear in the Settings UI search, consult the extension documentation for the correct configuration.

JetBrains IDEs (WebStorm, IntelliJ IDEA) do not yet offer native tsgo language service integration as of the RC. These IDEs continue to use the JavaScript-based language service. Teams using JetBrains can still run tsgo for command-line type-checking while relying on the bundled TypeScript service for editor features.

Handling Breaking Changes and Edge Cases

Behavioral Differences to Watch For

The Go compiler produces identical type errors for the vast majority of code, but the RC has known divergences in narrowing behavior within complex conditional type patterns. The Go type resolver evaluates some deeply nested conditional types with infer clauses in a different order, which can change resolution results.