> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Effect-TS/tsgo/llms.txt
> Use this file to discover all available pages before exploring further.

# Version pinning

> Understand how effect-tsgo manages its TypeScript-Go dependency, when to upgrade, and how to use the Nix flake.

`@effect/tsgo` is a **superset** of the official [TypeScript-Go](https://github.com/microsoft/typescript-go) compiler. Each published release embeds a pinned, validated snapshot of the upstream `tsgo` binary plus the Effect diagnostics layer on top. You get standard TypeScript-Go functionality alongside Effect-specific diagnostics, quick fixes, and refactors — from a single package.

## How pinning works

The upstream `typescript-go` commit that a given `@effect/tsgo` release is built against is recorded in two places:

* **`flake.nix`** — the `typescript-go-src` input pin used by the Nix build.
* **The Go submodule** — the `typescript-go/` directory in the source tree tracks the same commit.

When the upstream project ships new features or bug fixes, `effect-tsgo` adopts them in a subsequent release after validating compatibility with the Effect diagnostics layer. The most recent upstream update in 0.0.16 pulled in auto-import fixes, linked editing support, signature help trigger characters, JSON syntax validation, and formatting rule fixes.

<Note>
  You do **not** need to track the upstream `tsgo` releases separately. `@effect/tsgo` is the single binary to manage.
</Note>

## Current version

The current package is `@effect/tsgo` at version **0.0.17**. Because this project is in alpha, expect breaking changes between releases. Always check the [CHANGELOG](https://github.com/Effect-TS/tsgo/blob/main/_packages/tsgo/CHANGELOG.md) before upgrading.

<Warning>
  `@effect/tsgo` is currently in **alpha**. APIs, plugin options, and diagnostic behaviour may change between releases without a major version bump.
</Warning>

## Why pinning matters

Running `@effect/tsgo` against an arbitrary `tsgo` build would risk:

* **API mismatches** — the Effect diagnostics layer calls internal Go APIs that may shift between `tsgo` commits.
* **Incorrect diagnostics** — subtle changes in the TypeScript type-checker can silently alter diagnostic results.
* **Editor instability** — a mismatched binary can cause the language server to crash or produce duplicate results.

By pinning a specific `tsgo` commit and validating the combination before release, `effect-tsgo` guarantees a stable, tested pairing.

## When to upgrade

Upgrade `@effect/tsgo` when:

* A new release includes upstream `tsgo` fixes you need (consult the CHANGELOG for upstream changes included in each release).
* New Effect diagnostics or quick fixes are available that you want in your project.
* A bug in the language server or a specific diagnostic has been fixed.

You do **not** need to upgrade to match a specific upstream `tsgo` release — wait for an `@effect/tsgo` release that incorporates it.

## How to upgrade

<Steps>
  <Step title="Update the package">
    Install the latest version using your package manager:

    <Tabs>
      <Tab title="npm">
        ```bash theme={null}
        npm install @effect/tsgo@latest
        ```
      </Tab>

      <Tab title="pnpm">
        ```bash theme={null}
        pnpm add @effect/tsgo@latest
        ```
      </Tab>

      <Tab title="yarn">
        ```bash theme={null}
        yarn add @effect/tsgo@latest
        ```
      </Tab>

      <Tab title="bun">
        ```bash theme={null}
        bun add @effect/tsgo@latest
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Re-run the patch command">
    After installing, update the binary to the version shipped with the new release:

    ```bash theme={null}
    npx @effect/tsgo patch
    ```

    This replaces the previously patched binary with the new one. A backup of the old binary is created automatically.
  </Step>

  <Step title="Restart your editor">
    Reload or restart your editor's TypeScript language server to pick up the new binary. In VS Code, run the **TypeScript: Restart TS Server** command from the command palette.
  </Step>
</Steps>

## Supported platforms

`@effect/tsgo` ships pre-built binaries for the following platforms via optional npm dependencies:

| Platform              | Package                     |
| --------------------- | --------------------------- |
| macOS (Apple Silicon) | `@effect/tsgo-darwin-arm64` |
| macOS (Intel)         | `@effect/tsgo-darwin-x64`   |
| Linux (x64)           | `@effect/tsgo-linux-x64`    |
| Linux (ARM64)         | `@effect/tsgo-linux-arm64`  |
| Linux (ARM)           | `@effect/tsgo-linux-arm`    |
| Windows (x64)         | `@effect/tsgo-win32-x64`    |
| Windows (ARM64)       | `@effect/tsgo-win32-arm64`  |

The correct platform package is installed automatically by npm/pnpm/yarn based on the current OS and architecture.

## Nix flake

For Nix users, the repository exposes a `flake.nix` that builds a self-contained `effect-tsgo` binary from the pinned `typescript-go` and `TypeScript` sources, applying the Effect patch set on top.

```bash theme={null}
# Build the binary
nix build .#effect-tsgo

# Run it directly
nix run .#effect-tsgo
```

The flake pins both the `typescript-go-src` and `typescript-src` inputs to exact commits, ensuring fully reproducible builds:

```nix theme={null}
typescript-go-src = {
  url = "github:microsoft/typescript-go/50a70608da78b8ca200c4b1ba484330aa9e398eb?submodules=1";
  flake = false;
};
typescript-src = {
  url = "github:microsoft/TypeScript/2a3bed2b4265fa1173c88771a21ce044e6480f75";
  flake = false;
};
```

The Nix flake supports `x86_64-linux`, `aarch64-linux`, `x86_64-darwin`, and `aarch64-darwin`.

<Tip>
  The vendor hash in `flake.nix` must be updated whenever the pinned `typescript-go` commit changes. Use `_tools/update-flake-vendor-hash.sh` to regenerate it.
</Tip>