Effect v4 (Beta) - Development & Migration

Overview

Comprehensive guidance for Effect v4 development and migration from v3. This skill provides:

v4 Core Patterns - Guide to building new v4 code with ServiceMap, layers, generators, schema codecs
v3 → v4 Migration - Step-by-step migration guidance with API renames, behavior changes, and before/after examples

Status: Effect v4 is beta software under active development in effect-smol. The core programming model is stable, but effect/unstable/* modules may receive breaking changes in minor releases. For production use, review official v4 beta guidance and stability notes.

All bundled migration guides are sourced from the official effect-smol migration documentation.

Quick Triage

Building v4 Code

Core Effect types and combinators (Result, Option, Chunk, Duration): references/core-usage.md
Broader data types (DateTime, BigDecimal, HashSet, Redacted): references/data-types-advanced.md
Equality, Order, Hash, Equivalence semantics: references/behavior-traits.md
Expected errors vs defects, catch* combinators: references/error-management.md
Sandboxing, Cause inspection, catchCause: references/error-tooling.md
Exit and Cause structure, result inspection: references/exit-cause.md
Services and dependency injection (ServiceMap, layers): references/dependency-management.md
Layer construction, memoization, { local: true }: references/layer-patterns.md
Resource lifecycles, Scope, acquireRelease: references/resource-management.md
Running effects, Runtime removal, run boundaries: references/runtime-execution.md
Fibers, forkChild, forkDetach, fork options: references/concurrency.md
References (replaces FiberRef), ServiceMap.Reference: references/concurrency-advanced.md
Schedules, repetition, spaced/fixed/exponential: references/scheduling.md
Retries, backoff, schedule composition: references/scheduling-retry.md
Streams, queues, PubSub, STM: references/streams-queues-stm.md
HTTP clients and external APIs: references/http-client.md
HTTP servers and API definitions: references/http-server.md
Request batching and data loaders: references/request-resolver.md
Caching and memoization: references/caching.md
Configuration and config providers: references/configuration.md
Advanced config, redaction: references/configuration-advanced.md
Logs, metrics, tracing: references/observability.md
Logger/metrics/tracing setups and exporters: references/observability-examples.md
Wiring log/metric/trace layers: references/observability-wiring.md
Sequential workflows and yieldable patterns: references/generators.md
Schema validation, parsing, encoding (codecs): references/schema.md
Stream consumption with reducers (Sink): references/sink.md
Deterministic time in tests (TestClock): references/testing.md
Broader testing services and test layers: references/testing-stack.md
Command, FileSystem, Path, Terminal, KeyValueStore: references/platform-primitives.md
LLM workflows, planning, tool use via Effect AI: references/ai.md
Bundle-size constrained runtimes (Micro): references/micro.md
Migrating from Promise/async: references/migration-async.md
Common pitfalls and runtime errors: references/troubleshooting.md
Docs-to-guide map from llms.txt: references/docs-index.md

Migrating from v3

Full migration overview, quick-reference table, ordered checklist: references/migration.md
Runtime and run functions: references/migration/runtime.md
Error handling and error channel changes: references/migration/error-handling.md
Cause flattening and new structure: references/migration/cause.md
Services and environment changes (Context.Tag → ServiceMap.Service): references/migration/services.md
Fiber references and context locals: references/migration/fiberref.md
Forking and fiber APIs (fork → forkChild, etc.): references/migration/forking.md
Fiber keep-alive behavior changes: references/migration/fiber-keep-alive.md
Scope and resource lifecycle patterns: references/migration/scope.md
Layer memoization and Layer.fresh: references/migration/layer-memoization.md
Generator and Effect.gen changes: references/migration/generators.md
Yieldable protocol (non-Effect yieldables): references/migration/yieldable.md
Equality and structural comparison: references/migration/equality.md

Workflow

Ask which v3 APIs or files are in scope and which failures or regressions to avoid.
Open only the relevant migration notes from references/migration/.
Produce a mapping of v3 to v4 APIs, including before/after code snippets.
Call out behavior changes, edge cases, and test updates needed.
Provide a short, ordered migration checklist tailored to the code in question.

Example Requests

"Migrate this v3 Runtime usage to v4 and explain the new run functions."
"Update our v3 error handling to v4 and show before/after examples."
"We use FiberRefs and forking; what needs to change in v4?"
"Explain the generator/yieldable changes and update this Effect.gen usage."
"Do we need to change any Scope or Layer memoization behavior in v4?"

References - v4 Core

Comprehensive v4-specific guides (all updated for v4 APIs, no deprecated patterns):

references/core-usage.md - Core Effect types and combinators (Result, Option, Chunk)
references/data-types-advanced.md - DateTime, BigDecimal, HashSet, Redacted
references/behavior-traits.md - Structural equality by default, Equal, Order, Hash
references/error-management.md - catch* renames, catchReason, catchEager
references/error-tooling.md - catchCause, sandboxing, Cause inspection
references/exit-cause.md - Flattened Cause structure, Reason iteration
references/dependency-management.md - ServiceMap, services, layers
references/layer-patterns.md - Cross-provide memoization, { local: true }
references/resource-management.md - Scope.provide (was Scope.extend)
references/runtime-execution.md - Runtime<R> removed, run* at the edge
references/concurrency.md - forkChild/forkDetach, fork options, keep-alive
references/concurrency-advanced.md - ServiceMap.Reference (was FiberRef)
references/scheduling.md - Schedules and repetition
references/scheduling-retry.md - Retries and backoff
references/streams-queues-stm.md - Streams, queues, PubSub, STM
references/http-client.md - HTTP clients
references/http-server.md - HTTP servers
references/request-resolver.md - Request batching
references/caching.md - Caching and memoization
references/configuration.md - Configuration
references/configuration-advanced.md - Advanced config, redaction
references/observability.md - Logs, metrics, tracing
references/observability-examples.md - Concrete logger/metrics/tracing setups
references/observability-wiring.md - Wiring observability layers
references/generators.md - Effect.gen and yieldable patterns
references/schema.md - Schema codecs (decode/encode)
references/sink.md - Stream consumption with Sink
references/testing.md - TestClock and deterministic time
references/testing-stack.md - Test layer composition
references/platform-primitives.md - Command, FileSystem, Path, Terminal
references/ai.md - LLM workflows via Effect AI
references/micro.md - Bundle-size constrained runtimes
references/migration-async.md - Migrating from Promise/async
references/troubleshooting.md - Common pitfalls
references/versioning.md - Version guidance
references/docs-index.md - Docs-to-guide routing map

References - v3 → v4 Migration

references/migration.md - Start here: full overview, quick-reference table, ordered checklist
references/migration/cause.md - Cause flattening and structure
references/migration/equality.md - Equality and comparison changes
references/migration/error-handling.md - Error channel and catch* renames
references/migration/fiber-keep-alive.md - Fiber lifecycle changes
references/migration/fiberref.md - FiberRef and References changes
references/migration/forking.md - Fork, forkChild, forkDetach changes
references/migration/generators.md - Effect.gen pattern updates
references/migration/layer-memoization.md - Layer.fresh and memoization
references/migration/runtime.md - Runtime and run* functions
references/migration/scope.md - Scope and resource lifecycle
references/migration/services.md - Context.Tag → ServiceMap.Service
references/migration/yieldable.md - Yieldable protocol changes

effect-v4