Quickstart

Install @effect/tsgo in your existing TypeScript + Effect project using the interactive setup wizard.

Prerequisites

Before you begin, make sure you have:

• Node.js 18 or later
• npm, pnpm, or yarn
• An existing TypeScript project that uses Effect (V3 or V4)
• A tsconfig.json at the project root (or a known path)

You do not need to install @typescript/native-preview before running setup — the wizard will guide you through any additional steps.

Installation

1. Run the setup wizard

   From your project root, run:

   npx

   npx @effect/tsgo setup
   

   pnpm

   pnpm dlx @effect/tsgo setup
   

   yarn

   yarn dlx @effect/tsgo setup
   

   The interactive wizard walks you through each step of the setup:

   1. Select your tsconfig.json — the wizard detects tsconfig.json files in your project and lets you pick the right one.
   2. Add @effect/tsgo as a dependency — installs the package into your project’s package.json.
   3. Configure the tsconfig plugin — adds the @effect/language-service plugin entry to compilerOptions.plugins in your selected tsconfig.json.
   4. Adjust diagnostic options — lets you set initial severity preferences for individual rules.
   5. Editor hints — prints instructions for any additional editor configuration needed to activate the LSP.
2. Review your tsconfig.json

   After the wizard completes, your tsconfig.json will have a plugin entry similar to this:

   {
     "compilerOptions": {
       "plugins": [
         {
           "name": "@effect/language-service",
           // Maps rule names to severity levels. Use {} to enable all with defaults.
           "diagnosticSeverity": {},
           // When false, suggestion-level diagnostics are omitted from tsc output.
           "includeSuggestionsInTsc": true,
           // When true, suggestion diagnostics do not affect the tsc exit code.
           "ignoreEffectSuggestionsInTscExitCode": true,
           // When true, warning diagnostics do not affect the tsc exit code.
           "ignoreEffectWarningsInTscExitCode": false,
           // When true, error diagnostics do not affect the tsc exit code.
           "ignoreEffectErrorsInTscExitCode": false
         }
       ]
     }
   }
   

   You can adjust these options at any time. See the Plugin options reference for the full list.

3. Install the editor binary

   The wizard installs the npm package, but your editor needs access to the compiled effect-tsgo binary. Patch the @typescript/native-preview binary (which your editor likely already uses) by running:

   npx @effect/tsgo patch
   

   This replaces the tsgo binary inside @typescript/native-preview with the effect-tsgo binary and creates a backup of the original so you can restore it at any time.

   Run npx @effect/tsgo patch again whenever you update @effect/tsgo to a new version, to keep the binary in sync.

4. Configure your editor

   Point your editor’s TypeScript language server at the effect-tsgo binary. The exact configuration depends on your editor:

   • VS Code — see the VS Code setup section
   • Neovim — see the Neovim setup section
   • Other editors — see the Other editors section

   For the full walkthrough, go to the Editor setup guide.

5. Verify it works

   Open any .ts file that uses Effect. You should see:

   • Diagnostics — red/yellow underlines for Effect-specific issues like floating effects or missing yield*
   • Quick fixes — a lightbulb or code action menu offering one-click fixes
   • Completions — Effect.gen, Schema class, and directive snippets in autocomplete

   If diagnostics are not appearing, check the Troubleshooting guide.

Configure diagnostic severities

After the initial setup, you can adjust which rules are active and at what severity level using the interactive config command:

npx @effect/tsgo config

This opens an interactive rule picker against your existing tsconfig.json so you can enable, disable, or change the severity of individual diagnostics without editing JSON manually.

Next steps

Editor setup

Complete editor-specific configuration for VS Code, Neovim, and more.

Plugin options

Explore all available tsconfig plugin options.

Diagnostics overview

Browse all 50+ Effect-specific diagnostics and their default severities.

Refactors

Discover available code refactors and how to trigger them.