Effect Language Service (TypeScript-Go)

A wrapper around TypeScript-Go that builds the Effect Language Service, providing Effect-TS diagnostics and quick fixes. This project targets Effect V4 (codename: "smol") primarily and also Effect V3.

Installation

The setup of the TSGO version of the LSP can be performed via the command line interface:

# Interactive and guided setup for human friends
npx @effect/tsgo setup
# Non-interactive, for LLM friends
npx @effect/tsgo setup --help

This will guide you through the installation process, which includes:

1. Adding the @effect/tsgo dependency to your project.
2. Configuring your tsconfig.json to use the Effect Language Service plugin.
3. Adjusting plugin options to your preference.
4. Hinting at any additional editor configuration needed to ensure the LSP is active.

[!NOTE] At the moment, you still need a native TypeScript install alongside @effect/tsgo: typescript >= 7 (e.g. typescript@latest or typescript@next) or an alias such as @typescript/native. effect-tsgo patch tries typescript, then @typescript/native, and accepts --typescript-package <name> to try a custom package name first.

LSP-based linter

The Effect LSP doubles as a tool to perform type-aware linting of Effect code, and ships as well a way to emit additional Oxlint Type Aware rules.

Linting can occur either during the tsc typecheck phase (with the benefit of running typechecking only once and caching the output), or via a dedicated npx @effect/tsgo diagnostics --project tsconfig.json command (with typechecking occurring again), or via the Oxlint Patch.

See the Oxlint Setup guide for instructions on how to install and configure Oxlint with the Effect LSP.

When running in tsc mode, the Effect diagnostics are emitted as standard TypeScript diagnostics, and can be configured to affect the tsc exit code through the options ignoreEffectSuggestionsInTscExitCode, ignoreEffectWarningsInTscExitCode, and ignoreEffectErrorsInTscExitCode.

When running in dedicated diagnostics mode, the Effect diagnostics can be emitted in structured formats, which can be further processed by other tools.

Supported Package Versions

The following target package versions are supported by @effect/[email protected]:

| Component | Supported versions | |---|---| | TypeScript | 7.0.2, 7.1.0-dev.20261014.1 | | Oxlint | 1.85.0, 1.86.0, 1.87.0, 1.88.0 | | oxlint-tsgolint | 7.0.2003, 7.0.2004 |

Diagnostic Status

Some diagnostics are off by default or have a default severity of suggestion, but you can always enable them or change their default severity in the plugin options.

Refactor Status

| Refactor | V3 | V4 | Notes | |----------|----|----|-------| | asyncAwaitToFn | ✅ | ✅ | Convert async/await to Effect.fn | | asyncAwaitToFnTryPromise | ✅ | ✅ | Convert async/await to Effect.fn with Error ADT + tryPromise | | asyncAwaitToGen | ✅ | ✅ | Convert async/await to Effect.gen | | asyncAwaitToGenTryPromise | ✅ | ✅ | Convert async/await to Effect.gen with Error ADT + tryPromise | | debugPerformance | ❌ | ❌ | Insert performance timing debug comments | | effectGenToFn | ✅ | ✅ | Convert Effect.gen to Effect.fn | | functionToArrow | ✅ | ✅ | Convert function declaration to arrow function | | layerMagic | ✅ | ✅ | Auto-compose layers with correct merge/provide | | makeSchemaOpaque | ✅ | ✅ | Convert Schema to opaque type aliases | | makeSchemaOpaqueWithNs | ✅ | ✅ | Convert Schema to opaque types with namespace | | pipeableToDatafirst | ✅ | ✅ | Convert pipeable calls to data-first style | | removeUnnecessaryEffectGen | ✅ | ✅ | Remove redundant Effect.gen wrapper | | structuralTypeToSchema | ✅ | ✅ | Generate recursive Schema from type alias | | toggleLazyConst | ✅ | ✅ | Toggle lazy/eager const declarations | | togglePipeStyle | ✅ | ✅ | Toggle pipe(x, f) vs x.pipe(f) | | toggleReturnTypeAnnotation | ✅ | ✅ | Add/remove return type annotation | | toggleTypeAnnotation | ✅ | ✅ | Add/remove variable type annotation | | typeToEffectSchema | ✅ | ✅ | Generate Effect.Schema from type alias | | typeToEffectSchemaClass | ✅ | ✅ | Generate Schema.Class from type alias | | wrapWithEffectGen | ✅ | ✅ | Wrap expression in Effect.gen | | wrapWithPipe | ❌ | ✅ | Wrap selection in pipe(...) | | writeTagClassAccessors | ✅ | ➖ | Generate static accessors for Effect.Service/Tag classes |

Completion Status

| Completion | V3 | V4 | Notes | |------------|----|----|-------| | contextSelfInClasses | ✅ | ➖ | Context.Tag self-type snippets in extends clauses (V3-only) | | effectDataClasses | ✅ | ✅ | Data class constructor snippets in extends clauses | | effectSchemaSelfInClasses | ✅ | ✅ | Schema/Model class constructor snippets in extends clauses | | effectSelfInClasses | ✅ | ➖ | Effect.Service/Effect.Tag self-type snippets in extends clauses (V3-only) | | genFunctionStar | ✅ | ✅ | gen(function*(){}) snippet when dot-accessing .gen on objects with callable gen property | | effectCodegensComment | ✅ | ✅ | @effect-codegens directive snippet in comments with codegen name choices | | effectDiagnosticsComment | ✅ | ✅ | @effect-diagnostics / @effect-diagnostics-next-line directive snippets in comments | | rpcMakeClasses | ✅ | ➖ | Rpc.make constructor snippet in extends clauses (V3-only) | | schemaBrand | ✅ | ➖ | brand("varName") snippet when dot-accessing Schema in variable declarations (V3-only) | | serviceMapSelfInClasses | ✅ | ✅ | Service map self-type snippets in extends clauses |

Best Practices

Relationship to Official TypeScript-Go (tsgo)

Effect-tsgo is a superset of the official TypeScript-Go — it embeds a pinned version of tsgo with a small patch set on top and adds the Effect language service. This means effect-tsgo provides all standard TypeScript-Go functionality plus Effect-specific diagnostics, quick fixes, and refactors.

Use effect-tsgo instead of tsgo, not alongside it. Running both in parallel will produce duplicate diagnostics and degrade editor performance. Configure your editor to use effect-tsgo as your sole TypeScript language server.

Version Pinning

Each release of effect-tsgo is built against the versioned components recorded in _packages/tsgo/upstream.json. The Nix flake consumes the TypeScript next tag directly. When upstream tsgo releases new features or fixes, effect-tsgo will adopt them in a subsequent release after validating compatibility with the Effect diagnostics layer.

The npm compiler binaries load their TypeScript standard libraries from lib.*.d.ts files beside the executable. Each platform package ships the compiler for the latest TypeScript version as lib/tsc and other versions under artifacts/typescript/<version>/, each with its library files. If you relocate the executable returned by effect-tsgo get-exe-path, copy its library files into the same destination directory.

When to Upgrade

• Upgrade effect-tsgo when a new release includes upstream tsgo fixes you need or new Effect diagnostics you want.
• There is no need to track upstream tsgo releases separately — effect-tsgo is the single binary to manage.

Plugin Options

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@effect/language-service",
        // Controls Effect refactors. (default: true)
        "refactors": true,
        // Controls Effect diagnostics. (default: true)
        "diagnostics": true,
        // When false, suggestion-level Effect diagnostics are omitted from tsc CLI output. (default: true)
        "includeSuggestionsInTsc": true,
        // Controls Effect quickinfo. (default: true)
        "quickinfo": true,
        // Controls Effect completions. (default: true)
        "completions": true,
        // Controls Effect goto references support. (default: true)
        "goto": true,
        // Controls Effect rename helpers. (default: true)
        "renames": true,
        // When true, suggestion diagnostics do not affect the tsc exit code. (default: true)
        "ignoreEffectSuggestionsInTscExitCode": true,
        // When true, warning diagnostics do not affect the tsc exit code. (default: false)
        "ignoreEffectWarningsInTscExitCode": false,
        // When true, error diagnostics do not affect the tsc exit code. (default: false)
        "ignoreEffectErrorsInTscExitCode": false,
        // When true, disabled diagnostics are still processed so directives can re-enable them. (default: false)
        "skipDisabledOptimization": false,
        // Mermaid rendering service for layer graph links. Accepts mermaid.live, mermaid.com, or a custom URL. (default: "mermaid.live")
        "mermaidProvider": "mermaid.live",
        // When true, suppresses external Mermaid links in hover output. (default: false)
        "noExternal": false,
        // How many levels deep the layer graph extraction follows symbol references. (default: 0)
        "layerGraphFollowDepth": 0,
        // When true, suppresses redundant return-type inlay hints on supported Effect generator functions. (default: false)
        "inlays": false,
        // Package names that should prefer namespace imports. (default: [])
        "namespaceImportPackages": [],
        // Package names that should prefer barrel named imports. (default: [])
        "barrelImportPackages": [],
        // Package-level import aliases keyed by package name. (default: {})
        "importAliases": {},
        // Controls whether named reexports are followed at package top-level. (default: "ignore")
        "topLevelNamedReexports": "ignore",
        // Configures key pattern formulas for the deterministicKeys rule. (default: [{"target":"service","pattern":"default","skipLeadingPath":["src/"]},{"target":"custom","pattern":"default","skipLeadingPath":["src/"]}])
        "keyPatterns": [
          {
            "target": "service",
            "pattern": "default",
            "skipLeadingPath": [
              "src/"
            ]
          },
          {
            "target": "custom",
            "pattern": "default",
            "skipLeadingPath": [
              "src/"
            ]
          }
        ],
        // Enables matching constructors with @effect-identifier annotations. (default: false)
        "extendedKeyDetection": false,
        // Minimum number of contiguous pipeable transformations to trigger missedPipeableOpportunity. (default: 2)
        "pipeableMinArgCount": 2,
        // Unstable APIs allowed by package/module subtree or package/module#export name. (default: [])
        "allowedUnstableApis": [],
        // Experimental APIs allowed by package/module subtree or package/module#export name. (default: [])
        "allowedExperimentalApis": [],
        // Package names allowed to have multiple versions without triggering duplicatePackage. (default: [])
        "allowedDuplicatedPackages": [],
        // Controls which effectFnOpportunity quickfix variants are offered. (default: ["span"])
        "effectFn": [
          "span"
        ],
        // Maps rule names to severity levels. Use {} to enable diagnostics with rule defaults. (default: {})
        "diagnosticSeverity": {},
        // Ordered per-file diagnostic option overrides. (default: [{"include":["src/**/*.ts"],"options":{"diagnosticSeverity":{"floatingEffect":"error"}}}])
        "overrides": [
          {
            "include": [
              "src/**/*.ts"
            ],
            "options": {
              "diagnosticSeverity": {
                "floatingEffect": "error"
              }
            }
          }
        ]
      }
    ]
  }
}

The allowedUnstableApis and allowedExperimentalApis options selectively permit APIs marked @stability unstable and @stability experimental, respectively:

{
  "allowedUnstableApis": [
    "effect/http",
    "effect/rpc/RpcClient#make"
  ],
  "allowedExperimentalApis": ["my-package/Preview#make"]
}

A module entry permits that module and its descendants; an entry ending in #exportName permits only that module's exported API, including renamed imports and aliases. For example, effect/http/HttpClient permits the entire module, while effect/http/HttpClient#get permits only its exported get API. Matching is case-sensitive and respects path segments: effect/http does not permit effect/http-api. Per-file overrides replace the base list.

The import style options namespaceImportPackages, barrelImportPackages, importAliases, and topLevelNamedReexports can also be set per file in overrides. Auto-import, the import quick fixes, and the preferNamespaceImport and preferBarrelImport diagnostics all use the value resolved for the current file. A scoped value replaces the base value, so this override moves the legacy/ folder from namespace imports to barrel imports:

{
  "namespaceImportPackages": ["effect"],
  "overrides": [{
    "include": ["src/legacy/**/*.ts"],
    "options": {
      "namespaceImportPackages": [],
      "barrelImportPackages": ["effect"]
    }
  }]
}

apiStabilityLeak ignores exports marked @internal. The tag is the compiler's stripInternal declaration-emit marker, and it is honoured wherever it is written: on an exported declaration, on a named, star or namespace forwarding declaration, or on a namespace member. An untagged re-export of an internal target is ignored as well, because the forwarded target is not public API. A declaration that is not tagged keeps the export checked, so a public overload is still reported when only its implementation is marked @internal. Tagging a type does not hide it from public signatures: a public export that exposes an @internal type is still reported when that type is less stable. Properties and methods whose declarations are all marked @internal are excluded from the public surface, including in interfaces, classes, and augmentations. A merged property with any public declaration remains checked. An internal property does not exempt other public members of its containing export.

Inherited bases do not contribute to apiStabilityLeak when all their public members, including inherited members, are optional properties or methods with an explicit @stability stable, @stability unstable, or @stability experimental tag. This permits optional, explicitly tagged extensions of existing APIs such as Error. Required or untagged members and call, construct, or index signatures keep the base checked. Internal members are excluded when deciding whether a base qualifies. A derived type's own members remain checked independently. Direct references such as a property or parameter typed as the base still expose its declared stability.