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.
Unified Versioning
All Effect ecosystem packages now share a single version number and are released together. In v3, packages were versioned independently (e.g.[email protected], @effect/[email protected], @effect/[email protected]), making compatibility between packages difficult to track.
In v4: If you use [email protected], the matching SQL package is @effect/[email protected].
Package Consolidation
Many previously separate packages have been merged into the coreeffect package. Functionality from @effect/platform, @effect/rpc, @effect/cluster, and others now lives directly in effect.
Packages That Remain Separate
Packages that remain separate are platform-specific, provider-specific, or technology-specific:@effect/platform-*— Platform packages (Node, Browser, Bun)@effect/sql-*— SQL driver packages (PostgreSQL, MySQL, SQLite, etc.)@effect/ai-*— AI provider packages (OpenAI, Anthropic, etc.)@effect/opentelemetry— OpenTelemetry integration@effect/atom-*— Framework-specific atom bindings (React, Vue, Solid)@effect/vitest— Vitest testing utilities
effect.
Unstable Module System
v4 introduces unstable modules undereffect/unstable/* import paths. These modules may receive breaking changes in minor releases, while modules outside unstable/ follow strict semver.
Unstable Modules
Unstable modules include:ai— Language model integrationscli— Command-line interface toolscluster— Distributed systems primitivesdevtools— Development and debugging toolseventlog— Event logginghttp— HTTP client and serverhttpapi— HTTP API definitionsjsonschema— JSON Schema utilitiesobservability— Tracing and metricspersistence— Data persistence layersprocess— Process managementreactivity— Reactive programmingrpc— Remote procedure callsschema— Data validation and transformationsocket— WebSocket supportsql— SQL query buildersworkflow— Workflow orchestrationworkers— Worker thread management
effect/* namespace.
Performance and Bundle Size
The fiber runtime has been rewritten for reduced memory overhead and faster execution. The coreeffect package supports aggressive tree-shaking:
- Minimal Effect program: ~6.3 KB (minified + gzipped)
- With Schema: ~15 KB (minified + gzipped)
Migration Guides
Core Changes
Services
Context.Tag → ServiceMap.Service migrationError Handling
catch* renamings and new error handling patternsSchema v4
Schema validation and transformation changes
Additional Migration Topics
For complete migration coverage, see the source documentation:- Cause: Flattened structure
- Forking: Renamed combinators and new options
- Effect Subtyping: Yieldable interface
- Fiber Keep-Alive: Automatic process lifetime management
- Layer Memoization: Across
Effect.providecalls - FiberRef:
FiberRef→ServiceMap.Reference - Runtime:
Runtime<R>removed - Scope: Scope handling changes
- Equality: Equality comparison updates
Getting Started
To begin migrating your Effect v3 application:- Update all Effect packages to matching v4 beta versions
- Review the Services migration guide for the most common breaking change
- Update error handling patterns per the error handling guide
- If using Schema extensively, review the Schema v4 guide
- Test thoroughly, as some runtime behaviors have changed