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

main
mdx 232 lines 8.82 KB
Raw
1 ---
2 title: Local development
3 description: alchemy dev runs Workers in workerd with local simulators for KV, R2, D1, Queues, Hyperdrive, Workflows, Containers, and the Worker binding surface — browser rendering, images, email, cron, Stream, and more.
4 ---
5
6 import Terminal from "../../../components/Terminal.astro";
7
8 `alchemy dev` runs your Cloudflare stack on your machine. Workers
9 execute in workerd — the same runtime used in production — with
10 local simulators behind their bindings, websites run their
11 frameworks' own dev servers with native HMR, containers run in
12 Docker, and code changes hot reload in milliseconds.
13
14 ```sh
15 alchemy dev
16 ```
17
18 <Terminal content={`[g]✓[/g] [b]Bucket[/b] [d](Cloudflare.R2.Bucket)[/d] [g]created[/g] [d](local)[/d]
19 [g]✓[/g] [b]DB[/b] [d](Cloudflare.D1.Database)[/d] [g]created[/g] [d](local)[/d]
20 [g]✓[/g] [b]Worker[/b] [d](Cloudflare.Worker)[/d] [g]created[/g] [d](local → workerd)[/d]
21 [s2][d]• http://localhost:1337[/d]
22
23 [d]Watching for changes ...[/d]`} />
24
25 ## Workers run in workerd
26
27 Your Worker code executes in workerd with bindings wired to the
28 local simulators, so binding behavior matches what you deploy:
29
30 ```typescript
31 export const Cache = Cloudflare.KV.Namespace("Cache");
32
33 export default class Api extends Cloudflare.Worker<Api>()(
34 "Api",
35 { main: import.meta.url },
36 Effect.gen(function* () {
37 const kv = yield* Cloudflare.KV.ReadWriteNamespace(Cache);
38 return {
39 fetch: Effect.gen(function* () {
40 yield* kv.put("greeting", "hello");
41 const value = yield* kv.get("greeting");
42 return yield* HttpServerResponse.text(value ?? "");
43 }).pipe(Effect.orDie),
44 };
45 }).pipe(Effect.provide(Cloudflare.KV.ReadWriteNamespaceBinding)),
46 ) {}
47 ```
48
49 In dev, `kv.put` lands in a local KV simulator and the Worker
50 serves at `http://localhost:<port>`. Durable Objects run inside
51 the same workerd instance, cron triggers fire on their real
52 schedule (and the miniflare-compatible
53 `/cdn-cgi/handler/scheduled` route triggers them manually), and
54 because everything is a local process you can attach a debugger,
55 set breakpoints, and profile.
56
57 A local resource's id is `dev:`-prefixed, which doubles as proof
58 that no cloud call ran.
59
60 ## Websites run their own dev servers
61
62 Every `Cloudflare.Website.*` resource — Vite, Next.js, Astro,
63 Nuxt, SvelteKit, Waku, Octane, Foldkit, StaticSite — runs its
64 framework's own dev server under `alchemy dev`: native HMR, no
65 cloud resources. The site's `url` is the local dev server's
66 address:
67
68 ```typescript
69 const site = yield* Cloudflare.Website.Vite("Web");
70 // dev: site.url = http://localhost:5173 — Vite's own dev server, HMR included
71 // deploy: site.url = the deployed site
72 ```
73
74 See
75 [Frontend frameworks](/cloudflare/frontend/frontends).
76
77 ## Containers run in Docker
78
79 A `Cloudflare.Container` runs as a real Docker container on your
80 machine, driven by its Durable Object in the local workerd:
81
82 ```typescript
83 export class Sandbox extends Cloudflare.Container<
84 Sandbox,
85 { ping: () => Effect.Effect<string> }
86 >()("Sandbox") {}
87
88 export default Sandbox.make(
89 { main: import.meta.url },
90 Effect.gen(function* () {
91 return Sandbox.of({
92 ping: () => Effect.succeed("pong"),
93 fetch: Effect.succeed(HttpServerResponse.text("hello")),
94 });
95 }),
96 );
97 ```
98
99 All three image sources work locally: `main` (a bundled Effect
100 program), `context` (your own Dockerfile), and `image` (a
101 pre-built remote image).
102
103 ### FUSE mounts
104
105 A container can mount a FUSE filesystem locally, such as an R2
106 bucket through `s3fs` or `tigrisfs`, just as it can once deployed.
107 Every local container gets the Docker privileges FUSE needs:
108 `CAP_SYS_ADMIN`, the `/dev/fuse` device, and an unconfined AppArmor
109 profile.
110
111 ## What's emulated
112
113 These resources ship a local provider and run as simulators in
114 dev:
115
116 | Resource | Local behavior |
117 | ------------------------ | --------------------------------------------------------------------------------- |
118 | Workers | workerd, with hot reload and a `http://localhost:<port>` URL |
119 | Durable Objects | run inside the local workerd, including SQLite storage |
120 | KV Namespaces | local simulator; Node-side capability clients hit the same store |
121 | R2 Buckets | local simulator; an S3-compatible endpoint serves [presigned URLs](/cloudflare/data/r2-presigned-urls) |
122 | D1 Databases | local simulator; `migrations` and `importFiles` apply on every reconcile |
123 | Queues + consumers | local broker with batching, retry, and dead-letter semantics |
124 | Hyperdrive | connects directly to your database |
125 | Workflows | run locally with real step semantics |
126 | Containers | run as Docker containers on your machine |
127 | Secrets Store | local store seeded with the real (Redacted-sourced) values |
128 | Websites | the framework's own dev server (Vite, Astro, Next.js, Nuxt, SvelteKit, Waku, Octane, Foldkit, StaticSite) with native HMR |
129
130 Worker-only bindings are simulated too:
131
132 - **Email, both directions** — a `send_email` binding persists
133 messages as `.eml` files under `.alchemy/local/email`, and a
134 `POST` to `/cdn-cgi/handler/email` drives your `email()` handler
135 with accept, reject, and reply semantics.
136 - **Browser Rendering** — `env.BROWSER` drives a locally-launched
137 headless Chrome over CDP; `@cloudflare/puppeteer` works
138 unchanged.
139 - **Images** — `env.IMAGES` transforms run through sharp.
140 - **Stream** — uploads land in a local video store.
141 - **Tail consumers** — a local producer's trace events reach a
142 local tail Worker.
143 - **Secret keys** — `secret_key` CryptoKey bindings boot locally.
144 - **Access** — `dev: { access: { identity } }` stubs the
145 authenticated identity behind `ctx.access`, so gated paths are
146 testable without a login wall. See
147 [Protect a Worker with Access](/cloudflare/security/access).
148
149 Resources whose provider has no local implementation (a Vectorize
150 index, DNS records) deploy to the real cloud, into your personal
151 [stage](/environments/stages), so a stack that mixes emulated and
152 live-only resources just works.
153
154 ## Mix in the real cloud
155
156 `Alchemy.remote()` opts any resource (or a whole scope) out of
157 local emulation:
158
159 ```typescript
160 // Effect-native Worker
161 const browser = yield* Cloudflare.Browser("BROWSER").pipe(Alchemy.remote());
162
163 // async Worker env
164 env: { IMAGES: Cloudflare.Images.Images("IMAGES").pipe(Alchemy.remote()) }
165 ```
166
167 Local and live compose into hybrid topologies. Pin a queue live
168 and everything around it stays local — the local Worker produces
169 real messages into the real queue, and its local consumer drains
170 the same queue through a pull loop:
171
172 ```typescript
173 // the queue is real, even in dev
174 const Jobs = Cloudflare.Queues.Queue("Jobs").pipe(Alchemy.remote());
175 ```
176
177 Your dev session sees the same traffic as staging — messages
178 produced by deployed services or a teammate's session land in
179 your local handler.
180
181 Switching a resource between local and live (or dev → deploy)
182 plans a **replacement** — dev state never silently becomes cloud
183 state. See
184 [Local development](/environments/local-development) for the
185 shared semantics.
186
187 ## Custom port
188
189 ```typescript
190 export default Cloudflare.Worker("Worker", {
191 main: import.meta.url,
192 dev: {
193 port: 3000,
194 },
195 // ...
196 });
197 ```
198
199 ## Test against the local stack
200
201 The [test harness](/testing/test-harness) has the same dev mode —
202 `Test.make({ dev: true })` (available on both the Bun and Vitest
203 adapters, off by default) runs the suite's `deploy(Stack)` against
204 the local simulators instead of the cloud, no separate
205 `alchemy dev` terminal needed:
206
207 ```typescript
208 const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
209 providers: Cloudflare.providers(),
210 dev: true,
211 });
212 ```
213
214 Workers, Durable Objects, Workflows, and the simulated bindings all
215 run in workerd exactly as described above, and the stack's `url`
216 points at `http://localhost:<port>`. See
217 [Test harness → dev](/testing/test-harness#dev) and
218 [Tutorial Part 4](/cloudflare/tutorial/part-4).
219
220 ## Where next
221
222 - [Local development](/environments/local-development) — the
223 shared `alchemy dev` concepts: hot reload, `Alchemy.remote()`,
224 and dev vs deploy semantics.
225 - [Frontend frameworks](/cloudflare/frontend/frontends) —
226 framework dev servers under `alchemy dev`.
227 - [Stages](/environments/stages) — how live-in-dev resources stay
228 isolated per developer.
229 - [Testing](/testing) — run the same test suite against the local
230 simulators with `Test.make({ dev: true })`.
231 - [Local Providers](/infrastructure-as-code/local-provider) —
232 build the local implementation of a resource.