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

NPX Install

Tags

SKILL.md Content