How to Set Up typescript-go Locally: Complete Development Guide

To set up typescript-go locally, install Go 1.22+, clone the microsoft/typescript-go repository, and run go build -o tsgo ./cmd/tsgo to compile the native TypeScript compiler binary.

The microsoft/typescript-go repository provides a native Go port of the TypeScript compiler, offering significant performance improvements over the traditional Node.js-based toolchain. Setting up typescript-go locally requires building the tsgo binary from source and optionally integrating it with the NPM preview package or VS Code extension. This guide walks through the complete setup process using the actual source architecture found in the codebase.

Prerequisites

Before you set up typescript-go locally, ensure your environment meets these requirements:

• Go 1.22 or later: Required to compile the tsgo binary from the Go source code.
• Node.js 18+ and npm: Necessary for installing the @typescript/native-preview wrapper and VS Code integration tools.

Building the tsgo Binary from Source

The core executable is defined in cmd/tsgo/main.go, which handles CLI argument parsing, tsconfig.json loading, and compilation pipeline orchestration.

To build the binary:

git clone https://github.com/microsoft/typescript-go.git
cd typescript-go
go build -o tsgo ./cmd/tsgo

This produces the tsgo executable in your current directory. The main.go entry point invokes the execution engine located in internal/execute, which manages the build lifecycle.

Installing the NPM Preview Wrapper

For seamless integration with existing TypeScript workflows, install the global preview package:

npm install -g @typescript/native-preview

This wrapper forwards tsc-compatible commands to your locally built tsgo binary, allowing you to invoke the compiler via npx tsgo instead of referencing the binary directly.

VS Code Integration with LSP Support

The repository implements Language Server Protocol support in cmd/tsgo/lsp.go, enabling IntelliSense, diagnostics, and refactorings in editors.

To enable the native preview in VS Code:

1. Install the TypeScript Native Preview extension from the marketplace.
2. Add the following setting to your workspace configuration:

{
  "js/ts.experimental.useTsgo": true
}

When enabled, VS Code launches tsgo as the language service provider instead of the traditional TypeScript server, leveraging the Go-based LSP implementation for real-time code analysis.

Architecture Overview

Understanding these key internal packages helps troubleshoot build issues:

• internal/execute/watcher.go: Contains the file-watcher prototype for incremental builds and the logic that invokes the TypeScript front-end.
• internal/vfs/wrapvfs/wrapvfs.go: Wraps the host file system to provide the virtual file system API expected by the compiler.
• internal/packagejson/packagejson.go: Parses package.json files and resolves "exports" and "imports" for module resolution.
• internal/outputpaths/outputpaths.go: Computes output locations for emitted JavaScript, declaration files, and source maps.

Verification and Usage

Verify your installation by checking the version:

./tsgo -version

# Or with the NPM wrapper:

npx tsgo -version

Compile a TypeScript project using your local build:

./tsgo -p tsconfig.json

Start watch mode for incremental rebuilds (implemented in internal/execute/watcher.go):

./tsgo -w -p tsconfig.json

Start the LSP server manually (used by the VS Code extension):

./tsgo --lsp

Dev Container Setup

For automated environment configuration, use the pre-defined development container at .devcontainer/devcontainer.json. This configuration automatically installs Go and Node, builds the tsgo binary, and opens a ready-to-use VS Code environment, eliminating manual prerequisite management.

Summary

• Install prerequisites: Go 1.22+ and Node.js 18+ are required to build typescript-go locally and use the preview ecosystem.
• Build from source: Run go build -o tsgo ./cmd/tsgo to compile the binary from cmd/tsgo/main.go.
• Optional NPM wrapper: Install @typescript/native-preview globally to use tsgo through standard npx commands.
• VS Code integration: Enable "js/ts.experimental.useTsgo": true to activate the Go-based LSP server defined in cmd/tsgo/lsp.go.
• Key architecture: The compiler relies on internal/execute for builds, internal/vfs/wrapvfs for file system abstraction, and internal/packagejson for module resolution.

Frequently Asked Questions

What are the minimum system requirements to set up typescript-go locally?

You need Go 1.22 or later to compile the binary from source, and Node.js 18+ if you plan to use the NPM preview package or VS Code extension. The repository supports Linux, macOS, and Windows environments where Go is available.

How does the tsgo binary differ from the traditional tsc compiler?

The tsgo binary in cmd/tsgo/main.go is a native Go implementation that parses tsconfig.json and drives the compilation pipeline. While maintaining CLI compatibility with tsc, it executes through Go-based internal packages like internal/execute/watcher.go for builds and internal/vfs/wrapvfs/wrapvfs.go for file operations, delivering significantly faster compilation performance.

Can I use typescript-go with my existing VS Code projects?

Yes. Install the TypeScript Native Preview extension and set "js/ts.experimental.useTsgo": true in your workspace settings. This configures VS Code to launch the tsgo LSP server from cmd/tsgo/lsp.go instead of the standard TypeScript server, providing IntelliSense while maintaining compatibility with existing tsconfig.json configurations.

Is the watch mode fully implemented in typescript-go?

File-watching exists as a prototype implementation in internal/execute/watcher.go. You can invoke it with ./tsgo -w -p tsconfig.json, though it may not yet have full feature parity with the traditional TypeScript compiler's watch mode. The watcher monitors file changes and triggers selective compilation through the execution engine.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}