Effect v4 (Beta) - Development & Migration

Overview

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

1. v4 Core Patterns - Guide to building new v4 code with ServiceMap, layers, generators, schema codecs
2. 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

1. Ask which v3 APIs or files are in scope and which failures or regressions to avoid.
2. Open only the relevant migration notes from references/migration/.
3. Produce a mapping of v3 to v4 APIs, including before/after code snippets.
4. Call out behavior changes, edge cases, and test updates needed.
5. 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