Effect v4 tsgo tooling

Effect V4 TypeScript 7 Tooling

Use this skill to add Effect-aware TypeScript editor/type tooling to an existing TypeScript 7 / typescript@rc repository.

This setup is for editor and TypeScript analysis. It is not part of the Vite/runtime/build path unless the repo already runs a typecheck script that loads the TypeScript config and uses the patched or configured TypeScript-Go server.

Scope

This skill assumes the repo either:

• already uses typescript@rc / TypeScript 7, or
• the user explicitly asked to set up Effect tooling for a TypeScript 7 RC repo.

Do not apply this skill to a TypeScript 5/6 repo unless the user explicitly asked to move that repo to TypeScript 7 RC.

Do not install @typescript/native-preview in this skill. For TypeScript 7 RC repos, use the regular typescript@rc package.

Do not install @effect/language-service directly. With this setup, @effect/tsgo provides the Effect-aware TypeScript-Go language server. The @effect/language-service name is only used as the tsconfig.json plugin entry consumed by effect-tsgo.

What To Set Up

Install these as dev dependencies:

pnpm add -D @effect/tsgo typescript@rc

Prefer the repo's package manager. If it is not pnpm, use the existing lockfile/scripts to choose npm, yarn, or bun.

Equivalent examples:

npm install -D @effect/tsgo typescript@rc
yarn add -D @effect/tsgo typescript@rc
bun add -d @effect/tsgo typescript@rc

If typescript@rc is already installed, do not churn the dependency unnecessarily; add only @effect/tsgo.

Add the Effect language service plugin entry to the main TypeScript config used by editor tooling:

{
  "$schema": "https://raw.githubusercontent.com/Effect-TS/tsgo/refs/heads/main/schema.json",
  "compilerOptions": {
    "plugins": [
      {
        "name": "@effect/language-service"
      }
    ]
  }
}

Preserve existing compilerOptions, existing plugins, comments, formatting, and repo-specific tsconfig structure. If the repo has multiple tsconfigs, prefer the editor-facing root config, usually tsconfig.json, unless the project clearly uses a different solution config.

If there are existing TypeScript plugin entries, append the Effect plugin instead of replacing them.

Patching / Editor Integration

Prefer configuring the editor to use effect-tsgo as the TypeScript language server.

The binary path can be discovered with:

pnpm exec effect-tsgo get-exe-path

or with the equivalent package-manager command.

For editors that can point directly to a TypeScript language server binary, configure them to use that effect-tsgo path.

If the editor integration relies on the workspace TypeScript binary being patched, add or compose this script:

{
  "scripts": {
    "prepare": "effect-tsgo patch"
  }
}

If a prepare script already exists, do not overwrite it blindly. Compose it using the repo's existing script style.

Examples:

{
  "scripts": {
    "prepare": "existing-prepare && effect-tsgo patch"
  }
}

or, when the repo already uses a script runner:

{
  "scripts": {
    "prepare": "run-s prepare:*",
    "prepare:existing": "existing-prepare",
    "prepare:effect-tsgo": "effect-tsgo patch"
  }
}

Do not run normal tsgo alongside effect-tsgo. The repo should use effect-tsgo as the sole TypeScript-Go language server to avoid duplicate diagnostics and worse editor performance.

Workflow

1. Inspect package.json, lockfiles, and TypeScript config files.
2. Confirm the repo is actually using TypeScript 7 RC or is explicitly intended to use it.
3. Confirm whether the repo already has @effect/tsgo, typescript@rc or another TypeScript 7 package version, an effect-tsgo script, a prepare script, a compilerOptions.plugins entry for @effect/language-service, and editor config that points to a TypeScript language server binary.
4. Add only missing pieces.
5. If the repo is not already on TypeScript 7, do not silently upgrade it. Report that this skill is TypeScript 7-only.
6. Run install with the repo package manager.
7. Run effect-tsgo patch through the package manager if the repo uses the patching approach and install did not trigger prepare, or if patch status is unclear.
8. Run the repo's required validation commands. In this workspace, run pnpm format and pnpm lint.
9. If the repo has a typecheck script, run it too, unless it is known to be too expensive for the current task.
10. Summarize that this enables Effect-aware editor diagnostics, quick fixes, refactors, completions, and Layer graph tooling through effect-tsgo, and does not alter Vite/runtime behavior by itself.

Recommended Package Changes

For pnpm repos, the expected dependency shape is usually:

{
  "devDependencies": {
    "@effect/tsgo": "...",
    "typescript": "rc"
  }
}

Do not pin exact versions unless the repo already pins exact versions or the user asked for reproducible locking. Let the package manager lockfile record the resolved RC version.

If the repo uses catalogs, overrides, resolutions, workspace protocol dependencies, or central dependency management, follow the repo's existing dependency style.

Recommended tsconfig Shape

Minimal plugin entry:

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@effect/language-service"
      }
    ]
  }
}

Optional explicit plugin options may be added only when the user asks or the repo already uses explicit Effect diagnostic policy:

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@effect/language-service",
        "diagnostics": true,
        "refactors": true,
        "quickinfo": true,
        "completions": true,
        "goto": true,
        "renames": true,
        "includeSuggestionsInTsc": true,
        "ignoreEffectSuggestionsInTscExitCode": true,
        "ignoreEffectWarningsInTscExitCode": false,
        "ignoreEffectErrorsInTscExitCode": false
      }
    ]
  }
}

Avoid adding large option blocks unless they are needed. The default plugin behavior is usually preferred.

Substantiation

@effect/tsgo is the Effect-aware TypeScript-Go language server. It embeds a pinned TypeScript-Go version and adds the Effect language service layer on top.

The setup command:

npx @effect/tsgo setup

guides installation, tsconfig plugin configuration, plugin options, and editor setup. In an automated coding-agent workflow, prefer making the equivalent changes directly after inspecting the repo.

For TypeScript 7 RC repos, install TypeScript from the regular package:

pnpm add -D typescript@rc

The older native-preview package is for TypeScript 7 nightlies and is intentionally out of scope for this skill.

The Effect tsgo docs describe effect-tsgo as the single language-server binary to use instead of normal tsgo. Running both can cause duplicate diagnostics and worse editor performance.

The Effect tsgo diagnostics cover correctness, anti-patterns, Effect-native APIs, and style. Examples include floating Effects, missing yield*, missing returned yield*, missing Effect errors/context, bad Layer composition patterns, global Date/fetch/console/timers/random usage in Effect code, and V4 API guidance.

The refactors include async/await to Effect.gen, async/await to Effect.fn, async/await to Effect.tryPromise, Effect.gen to Effect.fn, wrapping/removing Effect.gen, pipe-style toggles, schema-oriented refactors, and service-related helpers where supported.

Caveats

• @effect/tsgo is alpha. Expect breaking changes and pin versions when stability matters.
• TypeScript 7 RC is close to stable but can still expose ecosystem compatibility issues, especially in tooling that imports TypeScript's programmatic API.
• Use effect-tsgo instead of normal tsgo, not alongside it.
• The patch must be rerun after upgrading @effect/tsgo so the patched TypeScript-Go binary stays in sync.
• This setup does not by itself make pnpm dev, vite build, or app runtime code use Effect tooling.
• Editors still need to use effect-tsgo, either by direct language-server configuration or through a patched workspace TypeScript-Go binary.
• Suggestion-level diagnostics may not fail CI by default. Do not claim CI enforcement unless the repo has a typecheck script and matching diagnostic severity config.
• Do not make runtime Effect architecture changes as part of this skill.

References

• Effect tsgo introduction: https://effect-ts-tsgo.mintlify.app/introduction
• Effect tsgo editor setup: https://effect-ts-tsgo.mintlify.app/editor-setup
• Effect tsgo diagnostics overview: https://effect-ts-tsgo.mintlify.app/diagnostics/overview
• Effect tsgo refactors: https://effect-ts-tsgo.mintlify.app/features/refactors
• Effect tsgo repository: https://github.com/Effect-TS/tsgo
• TypeScript 7.0 RC announcement: https://devblogs.microsoft.com/typescript/announcing-typescript-7-0-rc/