Skip to main content

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.

@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 install @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:
PlatformPackage
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us