TypeScript Native Preview

TypeScript Native Preview ships the in-progress native port of the TypeScript compiler, rewritten from the original JavaScript codebase (“Strada”) into Go (“Corsa”). It’s published to npm as @typescript/native-preview and installs a tsgo binary that behaves like tsc — type checking, declaration emit, JS emit, watch mode, build mode/project references, and incremental builds are all implemented — while the language service (LSP) is still being finished and the standalone JS API is not yet ready for general use.

The native port work that lived in this staging repository (microsoft/typescript-go) is now complete and has been merged back into the main microsoft/TypeScript repository, which is where TypeScript 7.0 development and issue tracking continue; this repo is being retired and archived. For 7.0 RC and later releases, the compiler is invoked as tsc the same way as TypeScript 6.0 — the tsgo name was only needed during the preview period.

What You Get

• A tsgo CLI binary (aliased to tsc for 7.0 RC+) that reads the same tsconfig.json and command-line flags as the existing TypeScript compiler
• Full type checking with the same diagnostics, error locations, and messages as TypeScript 6.0, plus JS emit, declaration (.d.ts) emit, watch mode, build mode/project references, and incremental builds
• JavaScript-specific inference and JSDoc support, intentionally trimmed of legacy features (e.g. Closure-style header files, expando constructor functions) that don’t exist in TypeScript
• An experimental, unstable JS/Node API (@typescript/native-preview/unstable/sync and /unstable/async) that spawns the Go binary and exposes AST, symbol, and type information over an RPC channel to the calling process
• A preview VS Code extension (published separately on the marketplace) that can be pointed at this same native compiler via a js/ts.experimental.useTsgo setting

Common Use Cases

• Trying the native compiler against an existing project’s tsconfig.json to gauge compile-time speed-up before TypeScript 7.0 ships
• Reporting behavioral differences between the Go port and TypeScript 6.0 by comparing tsgo/tsc output on real codebases
• Running the native compiler in CI on large monorepos to benchmark build and incremental-build times
• Using the experimental sync/async JS API to script programmatic type-checking or AST access against the native compiler process
• Switching an editor over to the native language service preview via the VS Code extension’s experimental setting

Under The Hood

Architecture The repo is organized as an idiomatic Go monorepo: cmd/tsgo is the CLI entrypoint, which drives internal/execute (the command-line runner) through a compiler pipeline that mirrors the original TypeScript’s stages one-for-one — internal/scanner, internal/parser, internal/binder, internal/checker, internal/printer — alongside internal/ls (language service) and internal/lsp (protocol server) for editor integration, internal/project for tsconfig/project-reference handling, internal/module for module resolution, and internal/vfs for a virtual filesystem abstraction that swaps in-memory or test filesystems for real OS access. The npm package (_packages/native-preview) is a thin JS-facing client layered on top of the compiled Go binary: it spawns or socket-connects to tsgo through a generated sync/async RPC client (src/api/sync, src/api/async) and a wire protocol (proto.generated.ts, encoder.generated.ts) that mirrors the Go-side API surface, so TypeScript AST and type objects are marshaled across a process boundary rather than reimplemented in JS. That client/server split is the defining architectural decision, and it means anything importing the JS API depends on a correctly versioned native binary being present at runtime.

Tech Stack The compiler core targets Go 1.26 (cmd/tsgo, internal/*) with a small dependency set — Microsoft/go-winio, go-json-experiment/json, and the golang.org/x/{sync,sys,term,text} packages — plus gotest.tools/v3 for test assertions; there’s no web framework since this is a CLI/compiler, though internal/lsp implements the Language Server Protocol over stdio/sockets for editor use. The npm-facing side is TypeScript itself, built with tsc -b under a custom hereby-based task runner (Herebyfile.mjs) rather than webpack or esbuild directly, formatted with dprint, watched with chokidar, and communicating over a vendored vscode-jsonrpc transport. The deployment target is a compiled native binary (bin/tsgo) distributed through npm, invoked either directly as a CLI (npx tsgo) or spawned as a subprocess by the JS API client.

Code Quality The Go core carries an extensive test suite — well over four thousand _test.go files across internal/ — using Go’s standard testing package augmented with gotest.tools/v3 assertions, a dedicated internal/fourslash harness ported from TypeScript’s own editor-test format, and a testutil/fixtures/testrunner setup that runs conformance tests against the upstream TypeScript test suite via a git submodule. Error handling favors explicit Go error returns and structured diagnostics (internal/diagnostics, internal/diagnosticwriter) over panics for expected failures, and a long, strict golangci-lint configuration (including a custom in-house linter plugin) enforces static analysis in CI alongside a CodeQL workflow. The TypeScript-facing API package has its own, much smaller test folder, and its generated client files are explicitly marked “AUTO-GENERATED — DO NOT EDIT,” underscoring that the npm package is a thin, mostly generated wrapper around the rigorously tested Go core.

API Design The published JS API surface is intentionally narrow and marked unstable — every entry point lives under ./unstable/sync or ./unstable/async rather than a single ergonomic root export — which is an honest reflection of the package’s preview status but adds friction for consumers, who also have to choose between a blocking sync client and an async one depending on their use case. Public types carry some TSDoc comments, but they’re sparse relative to the API’s overall surface area, and there’s no dedicated getting-started guide beyond the top-level README’s install/run instructions and npx tsgo --help. Compared to the long-established, hand-designed API of the existing typescript package (ts.createProgram and friends), this reads clearly as an early-stage, generated preview surface rather than one tuned for external developer ergonomics — which the package’s own README states outright.