@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 03:37 UTC

main
md 101 lines 4.29 KB
Rendered Raw
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 new features in patch releases
47 and breaking changes in minor releases. `@stability experimental` means it may
48 receive new features and breaking changes across patch versions. `@stability
49 stable` and APIs without a stability tag follow strict semver. Every module and
50 directly importable export declares its stability explicitly. Modules in
51 packages other than `effect` are currently `@stability unstable`.
52
53 APIs that expose a third-party dependency are also marked `@stability
54 unstable`, because that dependency's own releases can change them. This covers
55 accessors to underlying clients (for example `NodeRedis`'s `client` and `use`),
56 options typed as the dependency's options, and re-exports such as
57 `@effect/platform-node/Undici`. It includes the generated provider schemas in
58 the `@effect/ai-*` packages and the `@effect/opentelemetry` integration.
59
60 Imports using `effect/unstable/<module>` must drop the `unstable` segment.
61 For example, replace `effect/unstable/http` with `effect/http` and
62 `effect/unstable/ai/LanguageModel` with `effect/ai/LanguageModel`. There
63 are no compatibility exports for the old paths.
64
65 Unstable modules include: `ai`, `cli`, `cluster`, `devtools`, `eventlog`,
66 `http`, `http-api`, `jsonschema`, `observability`, `persistence`, `process`,
67 `reactivity`, `rpc`, `schema`, `socket`, `sql`, `workflow`, `workers`.
68
69 Moving these modules does not stabilize their APIs.
70
71 ### Performance and Bundle Size
72
73 The fiber runtime has been rewritten for reduced memory overhead and faster
74 execution. The core `effect` package supports aggressive tree-shaking. A
75 minimal Effect program bundles to 7.1 kB (minified + gzipped).
76
77 ---
78
79 ## Migration Guides
80
81 ### Import and API Rename Maps
82
83 - [v3 to v4 Import and API Rename Maps](./migration/v3-to-v4.md)
84
85 ### Core
86
87 - [Services: `Context.Tag` → `Context.Service`](./migration/services.md)
88 - [Cause: Flattened Structure](./migration/cause.md)
89 - [Error Handling: `catch*` Renamings](./migration/error-handling.md)
90 - [Forking: Renamed Combinators and New Options](./migration/forking.md)
91 - [Effect Subtyping Changes](./migration/yieldable.md)
92 - [Fiber Keep-Alive: Automatic Process Lifetime Management](./migration/fiber-keep-alive.md)
93 - [Layer Memoization Across `Effect.provide` Calls](./migration/layer-memoization.md)
94 - [FiberRef: `FiberRef` → `Context.Reference`](./migration/fiberref.md)
95 - [Runtime: `Runtime<R>` Removed](./migration/runtime.md)
96 - [Scope](./migration/scope.md)
97 - [Equality](./migration/equality.md)
98
99 ### Modules
100
101 - [Schema v4 Migration Guide](./migration/schema.md)