@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, 06:00 UTC

main
mdx 302 lines 9.95 KB
Raw
1 ---
2 title: Migrating from v1
3 description: Migrate your Alchemy v1 (async/await) project to Alchemy v2.
4 ---
5
6 import PackageManagers from "../../components/PackageManagers.astro";
7
8 export const pkgs = `alchemy@latest @alchemy.run/cloudflare@latest effect @effect/platform-bun @effect/platform-node`;
9
10 Alchemy v1 uses `async/await` with top-level `await` for
11 orchestration. Alchemy v2 replaces this with Effect generators for
12 type-safe error handling, composable retries, and declarative
13 resource wiring. The v1 documentation lives at
14 [v1.alchemy.run](https://v1.alchemy.run).
15
16 Your existing `async fetch` handlers **do not need to change** — you
17 can keep them as-is and still get all the benefits of the new engine.
18
19 ## Install v2
20
21 Each cloud provider is its own package in v2. Upgrade `alchemy` and add
22 the provider you deploy to, here `@alchemy.run/cloudflare`:
23
24 <PackageManagers add={pkgs} />
25
26 ## Step 1: Replace the Stack
27
28 In v1, you create an app with `await alchemy(...)` and finalize it
29 at the end:
30
31 ```typescript
32 // v1 — alchemy.run.ts
33 import alchemy from "alchemy";
34 import { Worker, Bucket } from "alchemy/cloudflare";
35
36 const app = await alchemy("my-app", {});
37
38 const bucket = await Bucket("bucket", {});
39 const worker = await Worker("worker", {
40 entrypoint: "./src/worker.ts",
41 bindings: { BUCKET: bucket },
42 });
43
44 console.log(worker.url);
45
46 await app.finalize();
47 ```
48
49 In v2, you export a default `Alchemy.Stack` and use `yield*` instead
50 of `await`:
51
52 ```typescript
53 // v2 — alchemy.run.ts
54 import * as Alchemy from "alchemy";
55 import * as Cloudflare from "@alchemy.run/cloudflare";
56 import * as Effect from "effect/Effect";
57
58 export const Bucket = Cloudflare.R2.Bucket("Bucket");
59
60 export const Worker = Cloudflare.Worker("Worker", {
61 main: "./src/worker.ts",
62 env: { Bucket },
63 });
64
65 export default Alchemy.Stack(
66 "MyApp",
67 { providers: Cloudflare.providers(), state: Cloudflare.state() },
68 Effect.gen(function* () {
69 const worker = yield* Worker;
70 return { url: worker.url };
71 }),
72 );
73 ```
74
75 Key differences:
76
77 - `entrypoint` is now called `main`
78 - `await` is now `yield*`
79 - No more `finalize()` — the Stack handles lifecycle automatically
80
81 ## Step 2: Keep your async handler
82
83 Your existing Worker runtime code does not need to change. The async
84 pattern declares bindings on the Worker's `env` prop and uses
85 `Cloudflare.InferEnv` to type the `env` object:
86
87 ```diff lang="typescript"
88 // alchemy.run.ts
89 +export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
90
91 export const Worker = Cloudflare.Worker("Worker", {
92 main: "./src/worker.ts",
93 env: { Bucket },
94 });
95 ```
96
97 Your handler stays the same — just update the type import:
98
99 ```diff lang="typescript"
100 // src/worker.ts
101 -import type { Env } from "../alchemy.run.ts";
102 +import type { WorkerEnv } from "../alchemy.run.ts";
103
104 export default {
105 - async fetch(request: Request, env: Env) {
106 + async fetch(request: Request, env: WorkerEnv) {
107 - const object = await env.BUCKET.get("key");
108 + const object = await env.Bucket.get("key");
109 return new Response(object?.body ?? null);
110 },
111 };
112 ```
113
114 `Cloudflare.InferEnv` derives a fully typed `env` object from the
115 `env` declared on the Worker. You get type safety on the binding
116 names and their APIs without using Effect in your runtime code.
117
118 :::tip
119 This is the recommended migration path. Get your infrastructure on v2
120 first, then optionally adopt Effect for runtime code later.
121 :::
122
123 ## Step 3: Pin your physical names
124
125 Your v1 state is not compatible with v2, so v2 starts from an empty
126 state store. Without extra steps, the first deploy would create
127 brand-new resources alongside your existing ones. Instead, you
128 [adopt](/cli/adopting-resources) the resources v1 already deployed —
129 no destroy, no downtime.
130
131 Adoption works by physical name: when a resource has no prior state,
132 the engine looks it up in the cloud by name and takes ownership of
133 what it finds. But v1 and v2 derive default names differently, so
134 without pinning, v2 would look for names that don't exist.
135
136 When you didn't set `name` explicitly, v1 derived it as:
137
138 ```
139 {app}-{id}-{stage}
140 ```
141
142 - `{app}` — the name you passed to `await alchemy("my-app")`
143 - `{id}` — the resource's logical ID, e.g. `await Bucket("bucket")`
144 - `{stage}` — the `--stage` value; defaults to `$ALCHEMY_STAGE`, then
145 your OS username (`$USER`), then `dev`
146
147 So the v1 example at the top of this page, deployed with
148 `--stage prod`, created a bucket named `my-app-bucket-prod` and a
149 worker named `my-app-worker-prod`. (Resources created inside a nested
150 scope get the scope names between `{app}` and `{id}`, and Worker names
151 are lowercased.)
152
153 Set the `name` prop on each v2 resource to that **exact** name:
154
155 ```typescript
156 export const Bucket = Cloudflare.R2.Bucket("Bucket", {
157 name: "my-app-bucket-prod", // v1's {app}-{id}-{stage}
158 });
159
160 export const Worker = Cloudflare.Worker("Worker", {
161 main: "./src/worker.ts",
162 name: "my-app-worker-prod", // v1's {app}-{id}-{stage}
163 env: { Bucket },
164 });
165 ```
166
167 If you did set `name` in v1, carry that value over unchanged. When in
168 doubt, confirm the live names in your v1 state (`.alchemy/` by
169 default) or the Cloudflare dashboard.
170
171 Because v1 baked the stage into the name, each stage has different
172 physical names. If you deploy several stages from the same config,
173 compute the name from the stage (e.g. an environment variable your CI
174 sets) instead of hardcoding one stage's suffix.
175
176 ## Step 4: Deploy with `--adopt`
177
178 ```sh
179 alchemy deploy --adopt
180 ```
181
182 For each resource, the engine finds the existing one by its physical
183 name and adopts it into v2 state, then reconciles it to the declared
184 config. `--adopt` tells the engine to take over resources it cannot
185 prove it owns — which is exactly the situation for everything v1
186 created. See [Adopting Resources](/cli/adopting-resources) for the
187 full ownership rules.
188
189 :::tip
190 Try the migration on a non-production stage first: deploy your v1
191 project to a fresh stage, then run the v2 adoption against it and
192 verify everything reconciles cleanly before touching prod.
193 :::
194
195 :::caution
196 After adopting, **do not run `destroy` in your v1 project** — its
197 state still points at the same physical resources, so destroying the
198 v1 stack would delete the resources v2 now manages. Delete the v1
199 state files (the `.alchemy/` directory, or your remote state store
200 entries) instead.
201 :::
202
203 From here on, deploys are normal:
204
205 ```sh
206 alchemy deploy
207 ```
208
209 ## (Optional) Adopt Effect for runtime code
210
211 When you're ready, you can switch to Effect-native Workers. This
212 gives you typed errors, composable retries, and Effect's `HttpServer`
213 integration.
214
215 Instead of declaring `env` bindings on the resource props, you bind
216 resources in the Worker's Construction phase using `yield*`:
217
218 ```diff lang="typescript"
219 // src/worker.ts
220 import * as Cloudflare from "@alchemy.run/cloudflare";
221 import * as Effect from "effect/Effect";
222 +import { HttpServerRequest } from "effect/http/HttpServerRequest";
223 import * as HttpServerResponse from "effect/http/HttpServerResponse";
224 import { Bucket } from "./bucket.ts";
225
226 -export default {
227 - async fetch(request: Request, env: WorkerEnv) {
228 - const object = await env.Bucket.get("key");
229 - return new Response(object?.body ?? null);
230 - },
231 -};
232 +export default Cloudflare.Worker("Worker",
233 + { main: import.meta.url },
234 + Effect.gen(function* () {
235 + const bucket = yield* Cloudflare.R2.ReadWriteBucket(Bucket);
236 +
237 + return {
238 + fetch: Effect.gen(function* () {
239 + const request = yield* HttpServerRequest;
240 + const key = request.url.split("/").pop()!;
241 + const object = yield* bucket.get(key);
242 + return object
243 + ? HttpServerResponse.text(yield* object.text())
244 + : HttpServerResponse.text("Not found", { status: 404 });
245 + }),
246 + };
247 + }),
248 +);
249 ```
250
251 The Worker resource declaration moves from `alchemy.run.ts` into the
252 Worker file itself (using `import.meta.url` as the `main`), and the
253 Stack just `yield*`-s the imported Worker:
254
255 ```diff lang="typescript"
256 // alchemy.run.ts
257 import * as Alchemy from "alchemy";
258 +import * as Cloudflare from "@alchemy.run/cloudflare";
259 import * as Effect from "effect/Effect";
260 +import Worker from "./src/worker.ts";
261 +import { Bucket } from "./src/bucket.ts";
262
263 -export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
264 -
265 -export const Worker = Cloudflare.Worker("Worker", {
266 - main: "./src/worker.ts",
267 - env: { Bucket },
268 -});
269
270 export default Alchemy.Stack(
271 "MyApp",
272 { providers: Cloudflare.providers(), state: Cloudflare.state() },
273 Effect.gen(function* () {
274 + const bucket = yield* Bucket;
275 const worker = yield* Worker;
276 return { url: worker.url };
277 }),
278 );
279 ```
280
281 ## Summary
282
283 | | v1 (async) | v2 (async style) | v2 (Effect style) |
284 | ------------ | ----------------------------- | ----------------------------- | ---------------------------------- |
285 | Stack | `await alchemy("name")` | `Alchemy.Stack("name", ...)` | `Alchemy.Stack("name", ...)` |
286 | Resources | `await Bucket(...)` | `Cloudflare.R2.Bucket(...)` | `Cloudflare.R2.Bucket(...)` |
287 | Worker entry | `entrypoint` | `main` | `main: import.meta.url` |
288 | Bindings | `bindings: { KEY: resource }` | `env: { Key: resource }` | `yield* Binding(ref)` |
289 | Runtime code | `async fetch(req, env)` | `async fetch(req, env)` | `Effect.gen(function* () { ... })` |
290 | Lifecycle | `await app.finalize()` | automatic | automatic |
291 | Type safety | runtime errors | typed `env` via `InferEnv` | full Effect type system |
292
293 ## Where next
294
295 - Tutorial — build a full app on v2 from scratch, on
296 [Cloudflare](/cloudflare/tutorial/part-1) or [AWS](/aws/tutorial/part-1)
297 - [Adopting Resources](/cli/adopting-resources) — the full ownership
298 rules behind `--adopt`
299 - [Bindings](/infrastructure-as-effects/binding) — what replaced v1 `bindings:`
300 - [Cloudflare](/cloudflare) — the Cloudflare provider hub
301 - [AWS](/aws) — the AWS provider hub
302 - [v1.alchemy.run](https://v1.alchemy.run) — the v1 documentation