3.6 KiB
Migrating from Effect v3 to Effect v4
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.
Background
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.
Versioning
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.
Package Consolidation
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.
Unstable Module System
v4 includes unstable modules under effect/* import paths. Their paths no
longer contain an unstable segment, but their API documentation is marked
with @stability unstable.
@stability unstable means an API may receive breaking changes in minor
releases. @stability experimental means it may receive breaking changes
across patch versions. APIs without a stability tag follow strict semver.
Imports using effect/unstable/<module> must drop the unstable segment.
For example, replace effect/unstable/http with effect/http and
effect/unstable/ai/LanguageModel with effect/ai/LanguageModel. There
are no compatibility exports for the old paths.
Unstable modules include: ai, cli, cluster, devtools, eventlog,
http, http-api, jsonschema, observability, persistence, process,
reactivity, rpc, schema, socket, sql, workflow, workers.
Moving these modules does not stabilize their APIs.
Performance and Bundle Size
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.
Migration Guides
Import and API Rename Maps
Core
- Services:
Context.Tag→Context.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→Context.Reference - Runtime:
Runtime<R>Removed - Scope
- Equality