Note: Effect v4 is currently in beta. APIs may change between beta releases. This guide will evolve as the beta progresses and community feedback is incorporated.
Effect v4 is a major release with structural and organizational changes across
the ecosystem. The core programming model — Effect, Layer, Schema,
Stream, etc. — remains the same, but how packages are organized, versioned,
and imported has changed significantly.
All Effect ecosystem packages now share a single version number and are
released together. In v3, packages were versioned independently (e.g.
effect@3.x, @effect/platform@0.x, @effect/sql@0.x), making compatibility
between packages difficult to track. In v4, if you use effect@4.0.0-beta.0,
the matching SQL package is @effect/sql-pg@4.0.0-beta.0.
Many previously separate packages have been merged into the core effect
package. Functionality from @effect/platform, @effect/rpc,
@effect/cluster, and others now lives directly in effect.
Packages that remain separate are platform-specific, provider-specific, or technology-specific:
@effect/platform-*— platform packages@effect/sql-*— SQL driver packages@effect/ai-*— AI provider packages@effect/opentelemetry— OpenTelemetry integration@effect/atom-*— framework-specific atom bindings@effect/vitest— Vitest testing utilities
These packages must be bumped to matching v4 beta versions alongside effect.
v4 introduces unstable modules under effect/unstable/* import paths.
These modules may receive breaking changes in minor releases, while modules
outside unstable/ follow strict semver.
Unstable modules include: ai, cli, cluster, devtools, eventlog,
http, httpapi, jsonschema, observability, persistence, process,
reactivity, rpc, schema, socket, sql, workflow, workers.
As these modules stabilize, they graduate to the top-level effect/* namespace.
The fiber runtime has been rewritten for reduced memory overhead and faster
execution. The core effect package supports aggressive tree-shaking — a
minimal Effect program bundles to ~6.3 KB (minified + gzipped). With Schema,
~15 KB.
- Services:
Context.Tag→ServiceMap.Service - Cause: Flattened Structure
- Error Handling:
catch*Renamings - Forking: Renamed Combinators and New Options
- Effect Subtyping → Yieldable
- Fiber Keep-Alive: Automatic Process Lifetime Management
- Layer Memoization Across
Effect.provideCalls - FiberRef:
FiberRef→ServiceMap.Reference - Runtime:
Runtime<R>Removed - Scope
- Equality