effect-setup

name	effect-setup
description	Bootstrap or align an Effect 4 project to the house setup — beta deps, tsgo + effect-tsgo patch, @effect/language-service tsconfig plugin, and the effect-solutions consultation rule. Use when a project needs Effect installed for the first time, when migrating from Effect 3 to Effect 4 beta, or when adding tsgo config to an existing Effect 4 project.
allowed-tools	Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
user-invocable	true

Effect Setup

Bootstrap or repair an Effect 4 project

• Effect 4 beta (effect@4.0.0-beta.x, @effect/platform-*) — not Effect 3.
• tsgo (TypeScript 7's native Go-based toolchain) for type-checking, patched for Effect via effect-tsgo patch from @effect/tsgo.
• @effect/language-service as a tsconfig plugin so editors get Effect-aware diagnostics and refactors.
• Bare-module imports (import * as Effect from "effect/Effect"), not import { Effect } from "effect".
• effect-solutions is consulted before writing Effect code — record this in AGENTS.md.

When to invoke

Run when the user says any of: "set up effect", "add effect to this project", "match the effect setup", "configure tsgo for effect", "wire effect-tsgo", or when starting a new project that will use Effect 4.

Do not run unprompted on a project that already has Effect 3 stable working — migrating to Effect 4 beta is a deliberate choice the user must opt into.

Workflow

Step 1 — Inspect the project

Before changing anything, read:

• package.json — what's installed, what version of effect (if any), whether @effect/tsgo is present.
• tsconfig.json — current compilerOptions, plugins, schema reference.
• mise.toml if present (the repo uses mise for tasks).
• AGENTS.md to see whether the effect-solutions rule is already documented.

Determine which of the three pieces (deps, tsconfig, AGENTS.md) are missing or out of date. Only touch the missing pieces — don't churn files that already match.

Step 2 — Confirm scope (only if ambiguous)

If the project already has effect@3.x installed, ask before bumping to beta. For greenfield projects with nothing in place, just proceed.

Step 3 — Apply each piece

3a. package.json — beta deps + scripts

Target shape (versions are the house baseline; let bun install resolve to current latest beta if the user prefers):

{
  "scripts": {
    "typecheck": "tsgo --noEmit",
    "prepare": "effect-tsgo patch"
  },
  "devDependencies": {
    "@effect/tsgo": "^0.19.0",
    "typescript": "7.0.2"
  },
  "dependencies": {
    "effect": "4.0.0-beta.92"
  }
}

For React projects, also add:

{
  "dependencies": {
    "@effect/atom-react": "^4.0.0-beta.92"
  }
}

For Bun/Node platform packages, pin to the same beta line as effect:

{
  "dependencies": {
    "@effect/platform-bun": "4.0.0-beta.92",
    "@effect/platform-node": "4.0.0-beta.92"
  }
}

Critical notes:

• prepare: "effect-tsgo patch" runs automatically after bun install. This patches the tsgo binary to understand Effect's type-level constructs. Without it, tsgo --noEmit reports spurious errors on Effect code.
• tsgo ships with stable typescript@7 — pin the current stable release (7.0.2) as a devDependency. The old @typescript/native-preview package is no longer needed.
• After editing package.json, run bun install so the prepare hook fires and patches tsgo.

3b. tsconfig.json — language service plugin

{
  "$schema": "https://raw.githubusercontent.com/Effect-TS/language-service/refs/heads/main/schema.json",
  "compilerOptions": {
    "lib": ["ESNext", "DOM", "DOM.Iterable"],
    "target": "ESNext",
    "module": "Preserve",
    "moduleDetection": "force",
    "jsx": "react-jsx",
    "allowJs": true,
    "types": ["bun"],

    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,
 
    "strict": true,
    "skipLibCheck": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,

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

Key bits to preserve when merging into an existing tsconfig:

• The $schema line — it gives the user JSON-schema completion for Effect-aware tsconfig fields.
• plugins: [{ "name": "@effect/language-service" }] — required for editor refactors like "Add missing yield*", "Add tag annotation", etc.
• verbatimModuleSyntax: true and module: "Preserve" — Effect 4 ships with explicit import type discipline; these settings keep the bundler honest.
• noUncheckedIndexedAccess: true — Effect's Schema and Match patterns assume this.

3c. AGENTS.md — effect-solutions rule

Append this section if not already present:

## Effect Best Practices

**IMPORTANT:** Always consult effect-solutions before writing Effect code.

Resolve the `effect-solutions` command (it may be installed in several places):

- **Local (npm):** `bunx effect-solutions` / `npx effect-solutions` if it's in the project's dependencies.
- **mise:** `mise exec -- effect-solutions` (or just `effect-solutions` if mise has shimmed it onto `PATH`).
- **Global:** `effect-solutions` directly if installed globally.

Then:

1. Run `effect-solutions list` to see available guides
2. Run `effect-solutions show <topic>...` for relevant patterns (supports multiple topics)
3. Search `~/.local/share/effect-solutions/effect` for real implementations

Topics: quick-start, project-setup, tsconfig, basics, services-and-layers, data-modeling, error-handling, config, testing, cli.

Never guess at Effect patterns - check the guide first.

Step 4 — Verify

After all writes:

bun install            # triggers `effect-tsgo patch`
bun run typecheck      # should succeed (or surface real errors, not Effect-internal ones)

If typecheck fails with errors inside node_modules/effect/**, the patch didn't take — re-run bunx effect-tsgo patch manually and report which file the error is in.

Import conventions (worth flagging to the user)

Effect 4 ships with deeply-nested module paths. The house style is bare-module imports, not the barrel:

// ✅ House style
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Schema from "effect/Schema";
import * as Atom from "effect/unstable/reactivity/Atom";
import * as AtomRegistry from "effect/unstable/reactivity/AtomRegistry";

// ❌ Avoid (works, but bigger bundles + slower TS)
import { Effect, Layer, Schema } from "effect";

Atom/AtomRegistry live under effect/unstable/reactivity/ in beta — that's not a typo, the API is still stabilizing.

What this skill does NOT do

• Does not write Effect application code. For that, follow the AGENTS.md rule and consult effect-solutions.
• Does not migrate Effect 3 codebases to Effect 4 — the API surface changed substantially. If asked, warn the user that this is a separate, larger task.
• Does not add @effect/platform-*, @effect/atom-react, or other ecosystem packages unless the project clearly needs them. Ask.

Quick reference: full file set for a new project

If the user wants everything wired from scratch with no existing code:

File	Purpose
package.json	Beta deps + typecheck / prepare scripts
tsconfig.json	@effect/language-service plugin, strict opts
AGENTS.md	effect-solutions rule
bunfig.toml (optional)	Bun preload stubs if targeting Workers
mise.toml (optional)	Task definitions matching package.json scripts

Create only the files the user actually wants — don't add mise.toml if they're not on mise.