Effect Handbook
Purpose
Use this as the single source of truth for Effect-related guidance in this repository. Sections are index buckets, not a reading order.
Routing Rules
- Do not read this handbook linearly.
- Pick one target file below.
- Follow
See alsoonly if that file is insufficient. - Read exactly one: pick one target file first; only follow
See alsoif needed. - Top-level routing: intent → exact file path; sections are index buckets, not reading order.
Quick Picks (Task -> File)
- Work with
Schema.Class/TaggedError/ decode / encode ->topics/schema.md - Handle
Option/Eithercontrol flow ->topics/option-either.md - Batch or cache data fetches with requests ->
topics/request-resolver.md - Build a CLI command ->
sections/20-cli.md - Configure CLI options/flags ->
topics/cli-options.md - Configure CLI positional args ->
topics/cli-args.md - Build interactive CLI prompts ->
topics/cli-prompt.md - Define HTTP endpoint + handler ->
sections/30-http-server.md - Build route-first HTTP app ->
topics/http-router.md - Derive typed HTTP client ->
topics/http-derive-client.md - Call external HTTP APIs ->
topics/http-client.md - Add Swagger/OpenAPI docs ->
topics/http-swagger.md - Handle multipart upload ->
topics/http-multipart.md - Implement streaming HTTP endpoint ->
topics/http-streaming.md - Use FileSystem/Path/Url/Terminal/KeyValueStore/Ndjson/Worker ->
sections/40-platform.md - NDJSON encode/decode streams ->
topics/platform-ndjson.md - Worker/WorkerRunner setup ->
topics/platform-worker.md - Run Stream into platform sink ->
topics/platform-stream-sink.md - Add typed RPC client/server ->
topics/rpc.md - Export telemetry with OpenTelemetry ->
topics/opentelemetry.md - Run SQL queries / transactions / streams ->
topics/sql-client.md - Configure SQL database drivers ->
topics/sql-drivers.md - Build schema-backed SQL resolvers ->
topics/sql-resolver-schema.md - Run SQL migrations ->
topics/sql-migrations.md - Write Effect tests ->
sections/50-testing.md - Use @effect/vitest modes ->
topics/testing-vitest.md - Retry/repeat policy ->
topics/schedule-retry.md - Stream processing ->
topics/stream.md - Context/Layer wiring ->
topics/layer-context.md - Queue producer-consumer ->
topics/queue.md - HTTP middleware/auth ->
topics/http-middleware.md - Config/env vars ->
topics/config.md
By Domain
- Core (Effect type, composition, execution, Schema, Option/Either, requests) ->
sections/00-foundations.md,sections/10-core-patterns.md,topics/schema.md,topics/option-either.md,topics/request-resolver.md - CLI (Command, Options, Args, Prompt) ->
sections/20-cli.md - HTTP (HttpApi, HttpApiBuilder, HttpRouter, HttpClient) ->
sections/30-http-server.md,topics/http-router.md,topics/http-client.md - SQL (
@effect/sql, drivers, resolvers, migrations) ->topics/sql-client.md,topics/sql-drivers.md,topics/sql-resolver-schema.md,topics/sql-migrations.md - Platform (FileSystem, Path, Url, Terminal, KeyValueStore, Ndjson, workers) ->
sections/40-platform.md - Distributed / observability (
@effect/rpc, OpenTelemetry exporters) ->topics/rpc.md,topics/opentelemetry.md - Testing (it.effect, it.live, it.scoped, TestClock) ->
sections/50-testing.md
By Primitive
Schema/Schema.Class/Schema.TaggedError->topics/schema.mdOption/Either->topics/option-either.mdRef/SynchronizedRef/FiberRef->topics/refs.mdCause/Exit->topics/cause-exit.mdSTM->topics/stm.mdScope/resource safety ->topics/scope-resource.mdDeferred->topics/deferred.mdSemaphore->topics/semaphore.mdCache->topics/cache.mdMatch->topics/match.mdLogger/Metric/tracing ->topics/observability.mdRequest/RequestResolver->topics/request-resolver.md- Concurrency/fibers/racing ->
topics/concurrency.md - Latch ->
topics/latch.md Stream(async iterables, pagination) ->topics/stream.mdSchedule(retry, repeat, backoff) ->topics/schedule-retry.mdLayer/Context(dependency injection) ->topics/layer-context.mdQueue(producer-consumer, back-pressure) ->topics/queue.mdPubSub(broadcast to subscribers) ->topics/pubsub.mdHttpApiMiddleware(auth, logging) ->topics/http-middleware.mdHttpClient/HttpClientRequest->topics/http-client.mdHttpRouter/HttpServer->topics/http-router.mdHttpApiClientderivation ->topics/http-derive-client.md- OpenAPI/Swagger ->
topics/http-swagger.md - Multipart ->
topics/http-multipart.md - HTTP streaming ->
topics/http-streaming.md - NDJSON ->
topics/platform-ndjson.md - Worker/WorkerRunner ->
topics/platform-worker.md - Stream + Sink integration ->
topics/platform-stream-sink.md RpcGroup/RpcServer/RpcClient->topics/rpc.mdNodeSdk/Otlp->topics/opentelemetry.mdSqlClient/ SQL fragments / transactions / streams ->topics/sql-client.md- SQL driver layers (
PgClient,MysqlClient,SqliteClient, etc.) ->topics/sql-drivers.md SqlResolver/SqlSchema->topics/sql-resolver-schema.md- SQL migrators (
PgMigrator,SqliteMigrator, etc.) ->topics/sql-migrations.md - Vitest integration ->
topics/testing-vitest.md Config(env, typed config) ->topics/config.md
Section Index
sections/00-foundations.md— Effect type, creation, composition, run boundariessections/10-core-patterns.md— Layers, retries, refs, schema-adjacent patterns, concurrency, streamssections/20-cli.md— Command, Options, Args, Prompt, subcommandssections/30-http-server.md— HttpApi, HttpApiEndpoint, HttpApiBuildersections/40-platform.md— HttpClient, HttpRouter, FileSystem, Path, Url, Terminal, KeyValueStore, Ndjson, workerssections/50-testing.md— it.effect, it.live, it.scoped, TestClock
Topic Index
topics/schema.md— Schema models, classes, tagged errors, decode/encodetopics/option-either.md— Option/Either control flow and pure error channelstopics/refs.md— Ref, SynchronizedRef, FiberReftopics/cause-exit.md— Cause, Exit, failure inspectiontopics/stm.md— STM transactions, TReftopics/scope-resource.md— Scope, acquireUseRelease, resource safetytopics/deferred.md— Deferred, one-shot signalingtopics/semaphore.md— Semaphore, bounded concurrencytopics/cache.md— Cache, TTL, lookuptopics/match.md— Match, exhaustive pattern matchingtopics/observability.md— Logger, Metric, tracingtopics/request-resolver.md— Request batching, dedupe, caching,Effect.requesttopics/concurrency.md— Concurrency settings, fibers, racing, interruptiontopics/latch.md— Latch gating and one-way release patternstopics/stream.md— Stream creation, consumption, transformations, combiningtopics/schedule-retry.md— Retry/repeat with exponential, jittered, custom schedulestopics/layer-context.md— Context.Tag, Layer, dependency compositiontopics/queue.md— Bounded/unbounded queues, offer/take, back-pressuretopics/pubsub.md— Broadcast to multiple subscribers, subscribe/publishtopics/http-middleware.md— HttpApiMiddleware.Tag, security, providestopics/http-client.md— Outgoing HTTP clients, request/response helperstopics/http-router.md— Route-first apps with HttpRouter/HttpServertopics/http-derive-client.md— Typed client derivation from HttpApitopics/http-swagger.md— Swagger/OpenAPI docs and annotationstopics/http-multipart.md— Multipart upload schemastopics/http-streaming.md— Streaming requests and responsestopics/platform-ndjson.md— NDJSON pack/unpack and schema channelstopics/platform-worker.md— Worker pools and WorkerRunnertopics/platform-stream-sink.md— Stream to sink/file integrationtopics/rpc.md— Typed RPC groups, protocols, client/server layerstopics/opentelemetry.md— OpenTelemetry exporters and SDK layerstopics/sql-client.md— SqlClient, tagged templates, fragments, transactions, streamstopics/sql-drivers.md— SQL driver packages, layers, transforms, driver-specific tagstopics/sql-resolver-schema.md— SqlResolver batching and SqlSchema query validationtopics/sql-migrations.md— Effect SQL migrator layers and migration filestopics/cli-options.md— Full options constructors and combinatorstopics/cli-args.md— Full args constructors and combinatorstopics/cli-prompt.md— Interactive prompts and compositiontopics/testing-vitest.md—it.effect,it.live,it.scoped,TestClocktopics/config.md— Config.string/integer, env fallback, nested config
Conventions
- Section files: What it is | When to use | When not to use | Minimal examples | Common pitfalls | See also
- Topic files: same structure, compact (~60–120 lines)
- Paths are relative to this SKILL.md; sections and topics use relative
../for cross-links
When to Use This Handbook
- Implementing Effect-based services, CLIs, HTTP APIs, or tests
- Looking up primitives (Schema, Option, Either, Stream, Schedule, Queue, Layer, Config)
- Building outgoing HTTP clients or route-first HTTP apps
- Using request batching / caching or typed RPCs
- Running SQL queries, transactions, migrations, or database-backed resolvers
- Resolving common pitfalls (run boundaries, retry layers, auth middleware)
- Choosing between similar primitives (Queue vs PubSub, Ref vs STM)
- Debugging Effect execution (run boundaries, fiber interruption, scoped resources)
Package References
effect— core runtime@effect/cli— Command, Options, Args, Prompt@effect/platform— HttpApi, HttpClient, HttpRouter, FileSystem, Path, Url@effect/platform-node— NodeContext, NodeHttpServer, NodeRuntime@effect/rpc— typed RPC groups, protocols, middleware@effect/opentelemetry— OTEL SDK and OTLP exporters@effect/vitest— it.effect, it.live, it.scoped@effect/sql— shared SqlClient, statements, schema helpers, resolvers, migrations@effect/sql-pg— PostgreSQL driver@effect/sql-mysql2— MySQL driver@effect/sql-mssql— Microsoft SQL Server driver@effect/sql-clickhouse— ClickHouse driver@effect/sql-libsql— libSQL driver@effect/sql-d1— Cloudflare D1 driver@effect/sql-sqlite-node/@effect/sql-sqlite-bun/@effect/sql-sqlite-wasm/@effect/sql-sqlite-react-native/@effect/sql-sqlite-do— SQLite drivers@effect/sql-drizzle/@effect/sql-kysely— SQL ORM/query-builder adapters
Specialized Packages Not Yet Routed In Detail
@effect/cluster@effect/workflow@effect/experimental
If one of these appears in a task, consult the reference repo README/examples first; this handbook does not yet have dedicated topic files for them.