| 1 | # Migrating from Effect v3 to Effect v4 |
| 2 | |
| 3 | > **Note:** If you run into a migration issue this guide doesn't cover, let us |
| 4 | > know on [Discord](https://discord.gg/effect-ts) or open an |
| 5 | > [issue](https://github.com/Effect-TS/effect/issues). |
| 6 | |
| 7 | ## Background |
| 8 | |
| 9 | Effect v4 is a major release with structural and organizational changes across |
| 10 | the ecosystem. The core programming model — `Effect`, `Layer`, `Schema`, |
| 11 | `Stream`, etc. — remains the same, but how packages are organized, versioned, |
| 12 | and imported has changed significantly. |
| 13 | |
| 14 | ### Versioning |
| 15 | |
| 16 | All Effect ecosystem packages now share a **single version number** and are |
| 17 | released together. In v3, packages were versioned independently (e.g. |
| 18 | `effect@3.x`, `@effect/platform@0.x`, `@effect/sql@0.x`), making compatibility |
| 19 | between packages difficult to track. In v4, if you use `effect@4.0.0`, |
| 20 | the matching SQL package is `@effect/sql-pg@4.0.0`. |
| 21 | |
| 22 | ### Package Consolidation |
| 23 | |
| 24 | Many previously separate packages have been merged into the core `effect` |
| 25 | package. Functionality from `@effect/platform`, `@effect/rpc`, |
| 26 | `@effect/cluster`, and others now lives directly in `effect`. |
| 27 | |
| 28 | Packages that remain separate are platform-specific, provider-specific, or |
| 29 | technology-specific: |
| 30 | |
| 31 | - `@effect/platform-*` — platform packages |
| 32 | - `@effect/sql-*` — SQL driver packages |
| 33 | - `@effect/ai-*` — AI provider packages |
| 34 | - `@effect/opentelemetry` — OpenTelemetry integration |
| 35 | - `@effect/atom-*` — framework-specific atom bindings |
| 36 | - `@effect/vitest` — Vitest testing utilities |
| 37 | |
| 38 | These packages must be bumped to matching v4 versions alongside `effect`. |
| 39 | |
| 40 | ### Unstable Module System |
| 41 | |
| 42 | v4 includes **unstable modules** under `effect/*` import paths. Their paths no |
| 43 | longer contain an `unstable` segment, but their API documentation is marked |
| 44 | with `@stability unstable`. |
| 45 | |
| 46 | `@stability unstable` means an API may receive breaking changes in minor |
| 47 | releases. `@stability experimental` means it may receive breaking changes |
| 48 | across patch versions. APIs without a stability tag follow strict semver. |
| 49 | |
| 50 | APIs that expose a third-party dependency are also marked `@stability |
| 51 | unstable`, because that dependency's own releases can change them. This covers |
| 52 | accessors to underlying clients (for example `NodeRedis`'s `client` and `use`), |
| 53 | options typed as the dependency's options, and re-exports such as |
| 54 | `@effect/platform-node/Undici`. It includes the generated provider schemas in |
| 55 | the `@effect/ai-*` packages and the `@effect/opentelemetry` integration. |
| 56 | |
| 57 | Imports using `effect/unstable/<module>` must drop the `unstable` segment. |
| 58 | For example, replace `effect/unstable/http` with `effect/http` and |
| 59 | `effect/unstable/ai/LanguageModel` with `effect/ai/LanguageModel`. There |
| 60 | are no compatibility exports for the old paths. |
| 61 | |
| 62 | Unstable modules include: `ai`, `cli`, `cluster`, `devtools`, `eventlog`, |
| 63 | `http`, `http-api`, `jsonschema`, `observability`, `persistence`, `process`, |
| 64 | `reactivity`, `rpc`, `schema`, `socket`, `sql`, `workflow`, `workers`. |
| 65 | |
| 66 | Moving these modules does not stabilize their APIs. |
| 67 | |
| 68 | ### Performance and Bundle Size |
| 69 | |
| 70 | The fiber runtime has been rewritten for reduced memory overhead and faster |
| 71 | execution. The core `effect` package supports aggressive tree-shaking — a |
| 72 | minimal Effect program bundles to ~6.3 KB (minified + gzipped). With Schema, |
| 73 | ~15 KB. |
| 74 | |
| 75 | --- |
| 76 | |
| 77 | ## Migration Guides |
| 78 | |
| 79 | ### Import and API Rename Maps |
| 80 | |
| 81 | - [v3 to v4 Import and API Rename Maps](./migration/v3-to-v4.md) |
| 82 | |
| 83 | ### Core |
| 84 | |
| 85 | - [Services: `Context.Tag` → `Context.Service`](./migration/services.md) |
| 86 | - [Cause: Flattened Structure](./migration/cause.md) |
| 87 | - [Error Handling: `catch*` Renamings](./migration/error-handling.md) |
| 88 | - [Forking: Renamed Combinators and New Options](./migration/forking.md) |
| 89 | - [Effect Subtyping Changes](./migration/yieldable.md) |
| 90 | - [Fiber Keep-Alive: Automatic Process Lifetime Management](./migration/fiber-keep-alive.md) |
| 91 | - [Layer Memoization Across `Effect.provide` Calls](./migration/layer-memoization.md) |
| 92 | - [FiberRef: `FiberRef` → `Context.Reference`](./migration/fiberref.md) |
| 93 | - [Runtime: `Runtime<R>` Removed](./migration/runtime.md) |
| 94 | - [Scope](./migration/scope.md) |
| 95 | - [Equality](./migration/equality.md) |
| 96 | |
| 97 | ### Modules |
| 98 | |
| 99 | - [Schema v4 Migration Guide](./migration/schema.md) |