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 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.

You do not need to track the upstream tsgo releases separately. @effect/tsgo is the single binary to manage.

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 before upgrading.

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

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

1. Update the package

   Install the latest version using your package manager:

   npm

   npm install @effect/tsgo@latest
   

   pnpm

   pnpm add @effect/tsgo@latest
   

   yarn

   yarn add @effect/tsgo@latest
   

   bun

   bun add @effect/tsgo@latest
   
2. Re-run the patch command

   After installing, update the binary to the version shipped with the new release:

   npx @effect/tsgo patch
   

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

3. 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.

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.

# 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:

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.

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.