# Best Practices for Using typescript-go: Native TypeScript Compilation Guide

> Master typescript-go with our native TypeScript compilation guide. Discover best practices for large codebases, IDE support, and embedding the compiler in Go apps. Optimize your workflow now.

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

---

**Use `npx tsgo` as a drop-in `tsc` replacement with `--incremental` for large codebases, enable `--lsp` for IDE support, and leverage the `execute.CommandLine` API when embedding the compiler in Go applications.**

The `typescript-go` repository delivers a native Go implementation of the TypeScript compiler designed to replace `tsc` while maintaining compatibility with TypeScript 6.0 and future 7.0 features. Following best practices for using typescript-go ensures optimal compilation performance whether you're running command-line builds, watch mode, or integrating the compiler directly into Go-based tooling.

## Architecture Overview

The `typescript-go` codebase follows a layered architecture that mirrors the original TypeScript compiler while leveraging Go's performance characteristics.

The **CLI entry point** in [`cmd/tsgo/main.go`](https://github.com/microsoft/typescript-go/blob/main/cmd/tsgo/main.go) parses arguments and delegates to either normal compilation, LSP mode (`--lsp`), or API mode (`--api`). The **command-line driver** in [`internal/execute/tsc.go`](https://github.com/microsoft/typescript-go/blob/main/internal/execute/tsc.go) implements the core `tsc` compatibility layer, containing functions like `CommandLine`, `tscCompilation`, and `tscBuildCompilation` that parse [`tsconfig.json`](https://github.com/microsoft/typescript-go/blob/main/tsconfig.json) via `tsoptions.ParseCommandLine` and manage the compilation lifecycle.

Key architectural layers include:

- **`internal/parser/*`** and **`internal/ast/*`** – Handle lexical scanning and AST generation
- **`internal/checker/*`** – Implements the full TypeScript type system and symbol resolution
- **`internal/execute/incremental/*`** and **`internal/execute/build/*`** – Drive incremental builds and multi-project orchestration
- **`internal/vfs/*`** – Provides the virtual file system abstraction essential for LSP and in-memory compilation

The driver creates a `compiler.Host` using `NewCachedFSCompilerHost` to connect the VFS to the type-checker, then calls `EmitAndReportStatistics` to produce output and diagnostics.

## Installation and Quick Start

Install the preview package to begin using the native compiler:

```bash
npm install @typescript/native-preview
npx tsgo --version  # Verify installation

```

The `tsgo` CLI works as a direct replacement for `tsc`. Place a [`tsconfig.json`](https://github.com/microsoft/typescript-go/blob/main/tsconfig.json) at your project root, then run:

```bash
npx tsgo -p .

```

The driver automatically searches upward for configuration files using `findConfigFile` (located in [`internal/execute/tsc.go`](https://github.com/microsoft/typescript-go/blob/main/internal/execute/tsc.go)), matching standard TypeScript behavior.

## Recommended Usage Patterns

### Standard Compilation with tsconfig.json

Keep your [`tsconfig.json`](https://github.com/microsoft/typescript-go/blob/main/tsconfig.json) in the repository root to leverage automatic configuration discovery. The `CommandLine` function in [`internal/execute/tsc.go`](https://github.com/microsoft/typescript-go/blob/main/internal/execute/tsc.go) handles upward directory traversal to locate the configuration file, identical to the original TypeScript compiler behavior.

Avoid combining incompatible flags such as `--watch` with `--listFilesOnly`, as the driver explicitly errors with `Option_watch_and_listFilesOnly_cannot_be_combined` when these are used together.

### Incremental Builds for Large Projects

Enable `--incremental` to trigger the optimized compilation path via `performIncrementalCompilation` (lines 83-108 in [`internal/execute/tsc.go`](https://github.com/microsoft/typescript-go/blob/main/internal/execute/tsc.go)):

```bash
npx tsgo -p . --incremental

```

This creates a `.tsbuildinfo` file that caches build state between runs, drastically reducing compile times for subsequent builds by reusing unchanged file information.

### Watch Mode Development

For active development, use watch mode to monitor file changes:

```bash
npx tsgo -w

```

The watch implementation resides in `createWatcher` within [`internal/execute/tsc.go`](https://github.com/microsoft/typescript-go/blob/main/internal/execute/tsc.go). While functional, this feature remains a prototype and may exhibit higher CPU usage with very large codebases. For production CI pipelines, prefer `--incremental` over `--watch`.

### Language Server Protocol (LSP) Integration

Enable the experimental VS Code setting `"js/ts.experimental.useTsgo": true` for IDE support, or launch the server manually:

```bash
npx tsgo --lsp

```

The LSP server implementation in [`cmd/tsgo/lsp.go`](https://github.com/microsoft/typescript-go/blob/main/cmd/tsgo/lsp.go) reuses the same `CommandLine` driver and `System` abstraction, ensuring consistency between CLI and IDE diagnostics. It supports full language service features including completions, quick-fixes, and real-time error reporting.

### Embedding the Go API Directly

For custom build pipelines or Go-based tooling, import the `internal/execute` package and call the driver programmatically:

```go
package main

import (
    "github.com/microsoft/typescript-go/internal/execute"
    "github.com/microsoft/typescript-go/internal/execute/tsc"
)

func main() {
    // Create the default system wrapping OS file system and stdout
    sys := execute.NewSystem()
    
    // Equivalent to `npx tsgo -p ./myproject`
    args := []string{"-p", "./myproject"}
    
    // Execute compilation
    result := execute.CommandLine(sys, args, nil) // nil = no testing harness
    
    // Check exit status against tsc.ExitStatus enum
    if result.Status != tsc.ExitStatusSuccess {
        // Diagnostics already written to sys.Writer()
        panic("Compilation failed")
    }
}

```

The `execute.System` abstraction provides file system access via `sys.FS()`, output writing via `sys.Writer()`, and path utilities. Use `execute.NewSystem()` for real OS operations, or provide a custom implementation for virtual file testing scenarios.

## Key Source Files and Implementation Details

Understanding these critical files helps debug issues and extend functionality:

- **[`cmd/tsgo/main.go`](https://github.com/microsoft/typescript-go/blob/main/cmd/tsgo/main.go)** – CLI bootstrap that parses `--lsp`, `--api`, and forwards to `execute.CommandLine`
- **[`internal/execute/tsc.go`](https://github.com/microsoft/typescript-go/blob/main/internal/execute/tsc.go)** – Central driver containing `CommandLine`, `performIncrementalCompilation`, and `createWatcher`
- **[`internal/execute/build/orchestrator.go`](https://github.com/microsoft/typescript-go/blob/main/internal/execute/build/orchestrator.go)** – Coordinates multi-project builds (`-b` flag) for monorepo scenarios
- **[`internal/checker/checker.go`](https://github.com/microsoft/typescript-go/blob/main/internal/checker/checker.go)** – Core TypeScript type system implementation
- **[`internal/vfs/wrapvfs/wrapvfs.go`](https://github.com/microsoft/typescript-go/blob/main/internal/vfs/wrapvfs/wrapvfs.go)** – Virtual file system wrapper enabling in-memory compilation
- **[`cmd/tsgo/api.go`](https://github.com/microsoft/typescript-go/blob/main/cmd/tsgo/api.go)** – HTTP API implementation for remote compilation services

## Summary

- **Install** the preview via `npm install @typescript/native-preview` for immediate `tsc` compatibility
- **Use `--incremental`** to leverage `performIncrementalCompilation` and reduce build times in CI/CD pipelines
- **Place [`tsconfig.json`](https://github.com/microsoft/typescript-go/blob/main/tsconfig.json) at the project root** to ensure `findConfigFile` locates your configuration automatically
- **Call `execute.CommandLine`** with `execute.NewSystem()` when embedding the compiler in Go applications
- **Enable `--lsp`** for IDE integration, but prefer incremental builds over `--watch` for production stability

## Frequently Asked Questions

### Does typescript-go support all TypeScript 6.0 features?

Yes, the implementation targets full TypeScript 6.0 compatibility and includes growing support for TypeScript 7.0 features. The checker in [`internal/checker/checker.go`](https://github.com/microsoft/typescript-go/blob/main/internal/checker/checker.go) implements the complete type system semantics, while the parser in `internal/parser/*` handles all standard TypeScript and JSX syntax constructs.

### How do I enable incremental compilation in typescript-go?

Pass the `--incremental` flag to trigger the optimized build path. The compiler creates a `.tsbuildinfo` file that `performIncrementalCompilation` in [`internal/execute/tsc.go`](https://github.com/microsoft/typescript-go/blob/main/internal/execute/tsc.go) uses to track file signatures and dependencies, skipping unchanged files in subsequent builds.

### Can I use typescript-go programmatically in my Go application?

Yes, import `github.com/microsoft/typescript-go/internal/execute` and call `execute.CommandLine(sys, args, nil)` where `sys` is an `execute.System` interface (typically created via `execute.NewSystem()`). This provides the same functionality as the CLI while allowing custom file system implementations through the `internal/vfs` abstraction.

### What is the difference between `--watch` and `--incremental` in typescript-go?

`--incremental` performs a one-shot compilation that writes build state to disk for faster subsequent builds, ideal for CI pipelines. `--watch` uses `createWatcher` in [`internal/execute/tsc.go`](https://github.com/microsoft/typescript-go/blob/main/internal/execute/tsc.go) to continuously monitor files and recompile on changes, suitable for development but currently consuming more CPU resources than the original TypeScript watch mode.