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

> Set up typescript-go locally with this complete guide. Install Go 1.22+, clone the repo, and build the native TypeScript compiler binary for efficient development.

- Repository: [Microsoft/typescript-go](https://github.com/microsoft/typescript-go)
- Tags: how-to-guide
- Published: 2026-04-25

---

**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`](https://github.com/microsoft/typescript-go/blob/main/cmd/tsgo/main.go)**, which handles CLI argument parsing, [`tsconfig.json`](https://github.com/microsoft/typescript-go/blob/main/tsconfig.json) loading, and compilation pipeline orchestration.

To build the binary:

```bash
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`](https://github.com/microsoft/typescript-go/blob/main/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:

```bash
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`](https://github.com/microsoft/typescript-go/blob/main/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:

```json
{
  "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`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/internal/packagejson/packagejson.go)**: Parses [`package.json`](https://github.com/microsoft/typescript-go/blob/main/package.json) files and resolves `"exports"` and `"imports"` for module resolution.
- **[`internal/outputpaths/outputpaths.go`](https://github.com/microsoft/typescript-go/blob/main/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:

```bash
./tsgo -version

# Or with the NPM wrapper:

npx tsgo -version

```

Compile a TypeScript project using your local build:

```bash
./tsgo -p tsconfig.json

```

Start watch mode for incremental rebuilds (implemented in [`internal/execute/watcher.go`](https://github.com/microsoft/typescript-go/blob/main/internal/execute/watcher.go)):

```bash
./tsgo -w -p tsconfig.json

```

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

```bash
./tsgo --lsp

```

## Dev Container Setup

For automated environment configuration, use the pre-defined development container at **[`.devcontainer/devcontainer.json`](https://github.com/microsoft/typescript-go/blob/main/.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`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/cmd/tsgo/main.go) is a native Go implementation that parses [`tsconfig.json`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/internal/execute/watcher.go) for builds and [`internal/vfs/wrapvfs/wrapvfs.go`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/cmd/tsgo/lsp.go) instead of the standard TypeScript server, providing IntelliSense while maintaining compatibility with existing [`tsconfig.json`](https://github.com/microsoft/typescript-go/blob/main/tsconfig.json) configurations.

### Is the watch mode fully implemented in typescript-go?

File-watching exists as a prototype implementation in [`internal/execute/watcher.go`](https://github.com/microsoft/typescript-go/blob/main/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.