build-effect-ts-v3

name	build-effect-ts-v3
description	Use if building TypeScript with Effect-TS v3 — Effect.gen, Layer, Schema, typed errors, Stream.

Build Effect-TS v3

Build production-grade TypeScript applications with Effect-TS v3. Effect<A, E, R> is a lazy, typed, immutable description of work; services and layers carry dependencies; Schema validates boundaries; fibers run structured concurrency; Stream carries pull-based async data. Ecosystem: @effect/platform, @effect/sql (+ 11 driver packages), @effect/rpc, @effect/cli, @effect/vitest, @effect/opentelemetry, plus @effect-atom/atom-react for React.

For the structured index of every reference file, read references/00-reference-map.md.

When to use

• Building, refactoring, debugging, or testing Effect-TS v3 code (effect@3.x)
• Implementing typed tagged errors, services and layers, fibers, streams, caching, scheduling, observability with the effect package
• Working with import { Effect, Layer, Schema, Stream } from "effect", Effect.gen(function*() { yield* … }), class X extends Effect.Service<X>()(...), class E extends Schema.TaggedError<E>("Tag")(...), Layer.provideMerge, Effect.fn("Service.method")
• Building HTTP servers/clients with @effect/platform, CLIs with @effect/cli, RPC with @effect/rpc, SQL with @effect/sql, tests with @effect/vitest, OTel with @effect/opentelemetry
• Building React frontends with @effect-atom/atom-react
• Migrating Promise / fp-ts / neverthrow / RxJS code to Effect, or operating in gradual-adoption / portable-utility mode

Do NOT use this skill for:

• Effect-TS v4 / v4 beta — strictly v3 only; v4 syntax (ServiceMap.Service, Schema.TaggedErrorClass, bare Effect.catch, Effect.forkChild, Effect.forkDetach, Schema.makeUnsafe, Result module) is forbidden, see references/anti-patterns/19-v4-syntax-do-not-use.md
• fp-ts, neverthrow, or RxJS codebases that do not plan to adopt Effect — only the migration/ docs apply
• Plain TypeScript without Effect, or other functional ecosystems (cats, ZIO)

Hard Rules (load-bearing — read before coding)

Rule	Recovery
Do not import from @effect/schema — deprecated since 3.10. Use import { Schema } from "effect"	references/schema/20-deprecated-effect-schema.md
Do not use v4 syntax: ServiceMap.Service, Schema.TaggedErrorClass, bare Effect.catch, Effect.forkChild, Effect.forkDetach, Schema.makeUnsafe, Result module	references/anti-patterns/19-v4-syntax-do-not-use.md
Do not throw inside Effect.gen — it becomes a defect. Use return yield* new TaggedError({...}) or Effect.fail(...)	references/anti-patterns/03-throw-in-gen.md
Do not write yield fx (no *) inside Effect.gen — yields the Effect object, not its value. Always yield* fx	references/anti-patterns/02-yield-without-star.md
Do not call Effect.runPromise / Effect.runSync inside library, service, or middleware code — only at program edges	references/anti-patterns/04-runpromise-mid-code.md, references/anti-patterns/12-runsync-in-services.md
Do not call Effect.all([...]) / Effect.forEach(...) / Stream.mapEffect without { concurrency: N } on lists > 5 items	references/anti-patterns/05-unbounded-parallelism.md, references/concurrency/07-bounded-parallelism.md
Do not use try / finally for cleanup — bypasses interruption. Use Effect.acquireRelease or Effect.ensuring	references/anti-patterns/15-manual-cleanup.md
Do not put null / undefined in domain types — use Option<T>	references/anti-patterns/10-null-undefined-domain.md
Do not use console.log — use Effect.log / logInfo / logError	references/anti-patterns/08-console-log.md
Do not read process.env directly — use Config.string("X") / Config.redacted("X")	references/anti-patterns/09-process-env.md
Do not use Option.getOrThrow — use Option.match	references/anti-patterns/11-option-getorthrow.md
Do not use as never / as any / as unknown to silence Effect type errors — find the real cause	references/anti-patterns/17-type-assertions.md
Do not catch with catchAll when catchTag / catchTags would preserve narrowing	references/anti-patterns/06-catchall-vs-catchtag.md
Do not invent generic error names (NotFoundError, Error) — use specific tagged errors (UserNotFoundError) so catchTag dispatches precisely	references/anti-patterns/07-generic-error-types.md
Do not call parameterized layer constructors inline at provide-sites — store layers in module-level constants for memoization	references/anti-patterns/14-inline-layer-construction.md

For the full anti-pattern catalog, read references/anti-patterns/01-overview.md.

Default Stance (load-bearing)

• Default to Effect.Service over Context.Tag for business services. Use Context.Tag for libraries with multiple implementations and for infrastructure with runtime injection (worker bindings, KV).
• Default to Schema.TaggedError over Data.TaggedError. The Schema form is serializable across RPC / HTTP and integrates with HttpApiSchema.annotations({ status: 404 }).
• Default to import { Schema } from "effect". The @effect/schema package is deprecated since 3.10. The migration is import-only.
• Default to Effect.fn("Service.method") for named functions to gain automatic span tracing and stack traces.
• Default to Effect.gen for sequential / branching logic; default to pipe for linear transformations.
• Default to { concurrency: N } on every Effect.all / Effect.forEach / Stream.mapEffect over a list of more than five items.
• Default to Layer.provideMerge over Layer.provide for incremental composition (consumers can also use the merged service). Use Layer.mergeAll for flat composition of independent layers.
• Default to NodeRuntime.runMain for entry points (handles SIGINT / SIGTERM gracefully). Use ManagedRuntime for non-Effect framework integration (Hono, Express, Next.js route handlers).
• Default to acquireRelease for resource lifecycles, never try / finally (which bypasses interruption).
• Default to return yield* when raising tagged errors inside Effect.gen so TypeScript narrows the control flow.

Recovery Moves (symptom → fix)

Symptom	Cause / fix
Missing 'X' in the expected Effect context / Effect<A, E, X> not assignable to Effect<A, E, never>	confused Layer.provide for Layer.provideMerge — see references/services-layers/12-layer-composition-gotchas.md, references/anti-patterns/13-layer-provide-confusion.md
Effect.cachedWithTTL is not a function / unexpected double-yield	API returns Effect<Effect<A,E,R>>; you yield twice — see references/caching/04-effect-cached.md
SubscriptionRef.unsafeMake is not a function	never call unsafeMake; use SubscriptionRef.make(initial) — see references/state/04-subscription-ref.md
AI hallucinated an API that doesn't exist	cross-check references/anti-patterns/18-ai-hallucinations.md and references/anti-patterns/19-v4-syntax-do-not-use.md
Effect resolved with null unexpectedly	Effect.promise swallowed the error as a defect — switch to Effect.tryPromise({ try, catch }), see references/anti-patterns/16-effect-promise-confusion.md
Tests pass with mocks but fail in prod	mocks were vi.mock. Replace with Layer.succeed(Service, mockImpl) — see references/testing/08-test-layers.md
Hanging Stream / never-ending program	infinite stream without take(N) / runHead — see references/streams/18-infinite-streams.md
OOM on large Effect.all	unbounded parallelism — add { concurrency: 10 }, see references/concurrency/07-bounded-parallelism.md
Finalizers not running on Ctrl-C	using try / finally instead of acquireRelease, or Effect.runPromise instead of NodeRuntime.runMain — see references/resource-management/03-acquire-release.md, references/platform/12-node-runtime.md
Stale logs / no traces in OTel	forgot NodeSdk.layer and OtlpTracer.layer — see references/observability/11-opentelemetry-setup.md
Header keys returned 404	header keys must be lowercase in HttpApiEndpoint.setHeaders — see references/http-server/05-headers.md
Cannot find module '@effect/schema'	deprecated package; switch to import { Schema } from "effect" — see references/schema/20-deprecated-effect-schema.md

Workflow / Routing

Load only the reference files needed for the current task.

1. Core: the Effect type, creation, running, combinators

Read references/core/01-effect-type.md, references/core/02-creating-effects.md, references/core/03-running-effects.md, references/core/04-pipelines.md, references/core/05-generators.md, references/core/06-gen-vs-pipe.md. For named service methods read references/core/07-effect-fn.md. For combinators read references/core/08-effect-all.md, references/core/09-effect-foreach.md, references/core/10-zip-and-tap.md, references/core/11-short-circuiting.md, references/core/12-effect-match.md.

2. Errors: typed tagged errors

Read references/error-handling/01-overview.md, references/error-handling/02-data-tagged-error.md, references/error-handling/03-schema-tagged-error.md, references/error-handling/04-catch-tag.md, references/error-handling/05-catch-tags.md, references/error-handling/06-catch-all.md, references/error-handling/07-cause-and-exit.md, references/error-handling/08-defects.md, references/error-handling/09-recovery-patterns.md, references/error-handling/10-error-accumulation.md, references/error-handling/11-yield-fail-pattern.md, references/error-handling/12-error-taxonomy.md, references/error-handling/13-error-remapping.md, references/error-handling/14-sandboxing.md.

3. Services and Layers: dependencies

Read references/services-layers/01-overview.md, references/services-layers/02-context-tag.md, references/services-layers/03-effect-service.md, references/services-layers/04-context-vs-effect-service.md, references/services-layers/05-context-reference.md, references/services-layers/06-layer-succeed.md, references/services-layers/07-layer-effect.md, references/services-layers/08-layer-scoped.md, references/services-layers/09-layer-merge.md, references/services-layers/10-layer-provide.md, references/services-layers/11-layer-providemerge.md, and the critical references/services-layers/12-layer-composition-gotchas.md. Runtime: references/services-layers/13-layer-memoization.md, references/services-layers/14-managed-runtime.md, references/services-layers/15-effect-provide.md, references/services-layers/16-layer-tap-debug.md, references/services-layers/17-fresh-vs-memoize.md.

4. Schema: validate boundaries (built into effect)

Read references/schema/01-overview.md, references/schema/02-schema-struct.md, references/schema/03-schema-class.md, references/schema/04-schema-tagged-class.md, references/schema/05-schema-tagged-error.md, references/schema/06-branded-types.md, references/schema/07-primitives.md, references/schema/08-collections.md, references/schema/09-unions-and-literals.md, references/schema/10-decoding.md, references/schema/11-encoding.md, references/schema/12-transforms.md, references/schema/13-filters.md, references/schema/14-annotations.md, references/schema/15-json-schema.md, references/schema/16-arbitrary.md, references/schema/17-equivalence-and-order.md, references/schema/18-recursive-schemas.md, references/schema/19-error-formatter.md, and the migration banner references/schema/20-deprecated-effect-schema.md.

5. Data Types: principled values

Read references/data-types/01-overview.md, references/data-types/02-option.md, references/data-types/03-option-patterns.md, references/data-types/04-either.md, references/data-types/05-data-struct.md, references/data-types/06-data-tuple-array.md, references/data-types/07-data-case.md, references/data-types/08-equal-and-hash.md, references/data-types/09-chunk.md, references/data-types/10-hashset-hashmap.md, references/data-types/11-readonly-array.md, references/data-types/12-duration.md, references/data-types/13-datetime.md, references/data-types/14-bigdecimal.md, references/data-types/15-redacted.md, references/data-types/16-brand.md, references/data-types/17-order-and-equivalence.md, references/data-types/18-function-utilities.md.

6. Pattern Matching: replace switch / if-chains

Read references/pattern-matching/01-overview.md, references/pattern-matching/02-match-value.md, references/pattern-matching/03-match-type.md, references/pattern-matching/04-match-tag.md, references/pattern-matching/05-match-when.md, references/pattern-matching/06-not-or-either.md, references/pattern-matching/07-exhaustive-vs-orelse.md.

7. Concurrency: bounded structured concurrency

Read references/concurrency/01-overview.md, references/concurrency/02-fork-types.md, references/concurrency/03-fiber-operations.md, references/concurrency/04-effect-race.md, references/concurrency/05-effect-all-concurrency.md, references/concurrency/06-effect-foreach-concurrency.md, and the rule references/concurrency/07-bounded-parallelism.md. Coordination: references/concurrency/08-semaphore.md, references/concurrency/09-deferred.md, references/concurrency/10-latch.md, references/concurrency/11-interruption.md, references/concurrency/12-stm.md, references/concurrency/13-effect-timeout.md, references/concurrency/14-effect-disconnect.md.

8. State

Read references/state/01-overview.md, references/state/02-ref.md, references/state/03-synchronizedref.md, references/state/04-subscription-ref.md, references/state/05-fiber-ref.md, references/state/06-state-patterns.md.

9. Resource Management: deterministic lifecycles

Read references/resource-management/01-overview.md, references/resource-management/02-scope.md, references/resource-management/03-acquire-release.md, references/resource-management/04-acquire-use-release.md, references/resource-management/05-effect-scoped.md, references/resource-management/06-add-finalizer.md, references/resource-management/07-effect-ensuring.md, references/resource-management/08-cleanup-order.md.

10. Streams: pull-based async data

Read references/streams/01-overview.md, references/streams/02-creating-streams.md, references/streams/03-stream-from-queue-pubsub.md, references/streams/04-stream-from-schedule.md, references/streams/05-stream-pagination.md, references/streams/06-transformations.md, references/streams/07-flattening.md, references/streams/08-merging-zipping.md, references/streams/09-mapEffect-concurrency.md, references/streams/10-stream-consumption.md, references/streams/11-sink.md, references/streams/12-channel.md, references/streams/13-error-handling.md, references/streams/14-backpressure.md, references/streams/15-batching.md, references/streams/16-broadcast-and-partition.md, references/streams/17-scope-and-stream.md, references/streams/18-infinite-streams.md.

11. Queue / PubSub: fiber coordination

Read references/queue-pubsub/01-overview.md, references/queue-pubsub/02-bounded-queue.md, references/queue-pubsub/03-dropping-sliding-queue.md, references/queue-pubsub/04-queue-operations.md, references/queue-pubsub/05-pubsub.md, references/queue-pubsub/06-producer-consumer.md, references/queue-pubsub/07-graceful-shutdown.md.

12. Caching and batching

Read references/caching/01-overview.md, references/caching/02-cache-make.md, references/caching/03-cache-operations.md, references/caching/04-effect-cached.md, references/caching/05-scoped-cache.md, references/caching/06-keyed-pool.md, references/caching/07-request-resolver.md.

13. Scheduling: retry, repeat, schedules

Read references/scheduling/01-overview.md, references/scheduling/02-built-in-schedules.md, references/scheduling/03-cron-schedule.md, references/scheduling/04-schedule-composition.md, references/scheduling/05-jitter-and-modify.md, references/scheduling/06-effect-retry.md, references/scheduling/07-effect-repeat.md, references/scheduling/08-schedule-conditions.md, references/scheduling/09-effect-delay.md.

14. Config: typed configuration via Config

Read references/config/01-overview.md, references/config/02-basic-config.md, references/config/03-config-redacted.md, references/config/04-config-collections.md, references/config/05-config-all-nested.md, references/config/06-config-validation.md, references/config/07-config-withDefault.md, references/config/08-config-providers.md, references/config/09-layer-set-config-provider.md.

15. Observability: logs, metrics, traces

Read references/observability/01-overview.md, references/observability/02-logging-basics.md, references/observability/03-structured-logs.md, references/observability/04-log-levels.md, references/observability/05-custom-logger.md, references/observability/06-tracing-basics.md, references/observability/07-span-scoped.md, references/observability/08-metrics-counter-gauge.md, references/observability/09-metrics-histogram-summary.md, references/observability/10-metric-tagged.md, references/observability/11-opentelemetry-setup.md, references/observability/12-otlp-exporters.md, references/observability/13-supervisor.md.

16. Platform: FS, Path, Command, Worker, runtimes

Read references/platform/01-overview.md, references/platform/02-filesystem.md, references/platform/03-path.md, references/platform/04-url.md, references/platform/05-command.md, references/platform/06-terminal.md, references/platform/07-keyvaluestore.md, references/platform/08-ndjson.md, references/platform/09-worker.md, references/platform/10-stream-sink-platform.md, references/platform/11-node-context.md, references/platform/12-node-runtime.md, references/platform/13-bun-platform.md.

17. HTTP Server: HttpApi

Read references/http-server/01-overview.md, references/http-server/02-defining-endpoints.md, references/http-server/03-path-params.md, references/http-server/04-query-and-payload.md, references/http-server/05-headers.md, references/http-server/06-grouping.md, references/http-server/07-handlers.md, references/http-server/08-error-responses.md, references/http-server/09-middleware.md, references/http-server/10-cors-and-logger.md, references/http-server/11-swagger.md, references/http-server/12-multipart.md, references/http-server/13-streaming-responses.md, references/http-server/14-custom-encoding.md, references/http-server/15-serving.md, references/http-server/16-platform-router.md, references/http-server/17-shutdown-and-signals.md.

18. HTTP Client

Read references/http-client/01-overview.md, references/http-client/02-fetch-http-client.md, references/http-client/03-request-building.md, references/http-client/04-response-decoding.md, references/http-client/05-derived-client.md, references/http-client/06-retries-and-timeouts.md, references/http-client/07-request-tracing.md, references/http-client/08-error-handling.md.

19. Testing with @effect/vitest

Read references/testing/01-overview.md, references/testing/02-it-effect.md, references/testing/03-it-live.md, references/testing/04-it-scoped.md, references/testing/05-it-layer.md, references/testing/06-test-clock.md, references/testing/07-test-random.md, references/testing/08-test-layers.md, references/testing/09-stateful-test-layers.md, references/testing/10-spy-layers.md, references/testing/11-testing-errors.md, references/testing/12-testing-resources.md, references/testing/13-testing-concurrency.md, references/testing/14-property-testing.md.

20. SQL with @effect/sql

Read references/sql/01-overview.md, references/sql/02-sql-client.md, references/sql/03-tagged-templates.md, references/sql/04-transactions.md, references/sql/05-sql-streams.md, references/sql/06-sql-resolver.md, references/sql/07-sql-schema.md, references/sql/08-sql-migrations.md, references/sql/09-driver-postgres.md, references/sql/10-driver-mysql.md, references/sql/11-driver-sqlite.md, references/sql/12-driver-other.md, references/sql/13-orm-adapters.md.

21. RPC

Read references/rpc/01-overview.md, references/rpc/02-rpc-group.md, references/rpc/03-rpc-server.md, references/rpc/04-rpc-client.md, references/rpc/05-rpc-middleware.md, references/rpc/06-rpc-streaming.md, references/rpc/07-rpc-cluster-intro.md.

22. CLI with @effect/cli

Read references/cli/01-overview.md, references/cli/02-command.md, references/cli/03-options.md, references/cli/04-options-combinators.md, references/cli/05-args.md, references/cli/06-args-combinators.md, references/cli/07-prompts.md, references/cli/08-subcommands.md, references/cli/09-providing-services.md, references/cli/10-config-files.md, references/cli/11-fallbacks.md, references/cli/12-completions.md.

23. React frontends with Effect Atom

Read references/frontend-atom/01-overview.md, references/frontend-atom/02-atom-make.md, references/frontend-atom/03-atom-families.md, references/frontend-atom/04-keep-alive.md, references/frontend-atom/05-react-hooks.md, references/frontend-atom/06-result-builder.md, references/frontend-atom/07-side-effect-atoms.md, references/frontend-atom/08-mutations.md, references/frontend-atom/09-cache-invalidation.md, references/frontend-atom/10-atoms-with-localstorage.md, references/frontend-atom/11-effect-runtime-bridge.md, references/frontend-atom/12-vercel-ai-sdk.md.

24. Migration from Promise / fp-ts / neverthrow / RxJS

Read references/migration/01-overview.md, references/migration/02-from-promise.md, references/migration/03-from-trycatch.md, references/migration/04-from-fp-ts.md, references/migration/05-from-neverthrow.md, references/migration/06-from-rxjs.md, references/migration/07-gradual-adoption.md, references/migration/08-portable-utility.md.

25. Architecture patterns

Read references/architecture/01-overview.md, references/architecture/02-domain-driven-design.md, references/architecture/03-hexagonal-architecture.md, references/architecture/04-repository-pattern.md, references/architecture/05-use-case-pattern.md, references/architecture/06-error-boundary-design.md, references/architecture/07-shared-kernel.md, references/architecture/08-effect-language-server.md.

26. End-to-end greenfield playbooks

Read references/workflows/01-greenfield-cli.md, references/workflows/02-greenfield-http-api.md, references/workflows/03-greenfield-react-spa.md, references/workflows/04-greenfield-nextjs.md, references/workflows/05-adding-effect-existing.md, references/workflows/06-microservice.md, references/workflows/07-background-worker.md, references/workflows/08-mcp-server.md, references/workflows/09-ai-agent.md.