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

main
mdx 208 lines 7.61 KB
Raw
1 ---
2 title: Local development
3 description: How alchemy dev provides hot reloading, local execution, and local emulation with per-resource opt-in to real cloud services.
4 ---
5
6 import Terminal from "../../../components/Terminal.astro";
7
8 `alchemy dev` runs your stack on your machine. Your compute runs
9 locally (Workers in workerd, Lambda and ECS in Docker
10 containers), the services around it are emulated, and code
11 changes hot reload in milliseconds. `Alchemy.remote()` runs any
12 resource against the real cloud when you need it.
13
14 This page covers the concepts shared by every cloud. For what
15 each cloud emulates and how, see the dedicated guides:
16
17 - **[Cloudflare local development](/cloudflare/local-development)**
18 — Workers in workerd; simulators for KV, R2, D1, Queues,
19 Hyperdrive, Workflows, Containers, and the Worker binding
20 surface (browser rendering, images, email, cron, Stream, …).
21 - **[AWS local development](/aws/local-development)** — Lambda
22 and ECS in Docker containers with close to 40 emulated services
23 (S3, DynamoDB, SQS, SNS, EventBridge, API Gateway, …), no AWS
24 account required.
25
26 ## How it works
27
28 ```sh
29 alchemy dev
30 ```
31
32 <Terminal content={`[g]✓[/g] [b]Bucket[/b] [d](Cloudflare.R2.Bucket)[/d] [g]created[/g] [d](local)[/d]
33 [g]✓[/g] [b]DB[/b] [d](Cloudflare.D1.Database)[/d] [g]created[/g] [d](local)[/d]
34 [g]✓[/g] [b]Worker[/b] [d](Cloudflare.Worker)[/d] [g]created[/g] [d](local → workerd)[/d]
35 [s2][d]• http://localhost:1337[/d]
36
37 [d]Watching for changes ...[/d]`} />
38
39 Three things happen:
40
41 1. **Emulatable services run locally** — resources whose provider
42 ships a local implementation are created as local simulators
43 with `dev:`-prefixed ids. No cloud calls.
44 2. **Your code runs locally** — Workers execute in workerd,
45 Lambda functions and ECS tasks in Docker containers, websites
46 on their framework's own dev server — with bindings wired to
47 the local simulators.
48 3. **File changes hot reload** — edit your code and the running
49 compute swaps in the new code without a redeploy.
50
51 Resources whose provider has no local implementation deploy to
52 the real cloud, into the [`dev_$USER` stage](/environments/stages)
53 by default — separate from `alchemy deploy`'s `live_$USER` stage,
54 so a bare `alchemy dev` cannot replace a stage you deployed. A
55 stack that mixes emulated and live-only resources just works. See
56 [Dev vs deploy](#dev-vs-deploy) for tearing a dev stage down.
57
58 ## Hot module reloading
59
60 <Terminal content={`[d]Watching for changes ...[/d]
61
62 [y]↻[/y] [d]src/worker.ts changed[/d]
63 [s2][d]• Rebuilding worker ...[/d]
64 [g]✓[/g] [b]Worker[/b] [d]reloaded in 42ms[/d]
65
66 [y]↻[/y] [d]src/api.ts changed[/d]
67 [s2][d]• Rebuilding worker ...[/d]
68 [g]✓[/g] [b]Worker[/b] [d]reloaded in 38ms[/d]`} />
69
70 - Code changes take effect in **milliseconds**, not minutes
71 - Resources stay running across reloads — only your application
72 code is rebuilt
73
74 Arbitrary dev processes — Vite, Next, anything with a dev server —
75 join the loop via [Command.Dev](/command/dev-servers): started by
76 `alchemy dev`, restarted when its inputs change, and a no-op on
77 deploy.
78
79 ## Local by default, live on demand
80
81 In dev, emulatable resources are simulators. A local resource's
82 id is `dev:`-prefixed, which doubles as proof that no cloud call
83 ran.
84
85 The local simulators reach beyond your compute's bindings.
86 Node-side capability clients follow the same rule: a seed script
87 in an [Action](/infrastructure-as-code/action) that writes to a
88 `dev:` KV Namespace or S3 bucket lands in the same local
89 simulator your Worker or Lambda reads.
90
91 Every other resource runs live in dev automatically, and
92 `Alchemy.remote()` (below) runs an emulatable resource against
93 the real cloud when local fidelity isn't enough.
94
95 ## Debugging
96
97 Because your code runs locally, you can attach a debugger:
98
99 - Set breakpoints in your IDE
100 - Inspect variables and call stacks
101 - Profile performance
102
103 ## Running a resource live in dev
104
105 `Alchemy.remote()` opts a resource out of local emulation — "run
106 this live even in dev":
107
108 ```typescript
109 import * as Alchemy from "alchemy";
110
111 const worker = yield* Worker("Api", { ... }).pipe(Alchemy.remote());
112 ```
113
114 During `alchemy deploy` the pin is a no-op — everything is live
115 anyway. If a remote resource needs credentials you don't have,
116 `alchemy dev` tells you before touching anything.
117
118 ### Opt out a whole scope
119
120 ```typescript
121 yield* Effect.gen(function* () {
122 const api = yield* Worker("Api", { ... });
123 const site = yield* Worker("Site", { ... });
124 }).pipe(Alchemy.remote());
125 ```
126
127 The policy is ambient and captured at registration (like
128 `adopt()`), so everything inside the scope runs live. Resources
129 with no local emulation already run live in dev — `remote()` on
130 them is a no-op.
131
132 Local and live compose into hybrid topologies — a local Worker
133 producing into a live queue whose local consumer drains it, or a
134 local Lambda reading a live Secrets Manager secret. See the
135 per-cloud guides for examples.
136
137 ### Switching is a replacement
138
139 When a resource moves between local and live — you deploy after a
140 dev session, or add/remove `remote()` — it's planned as a
141 **replacement**: the new instance is created live, and the local
142 one (the workerd instance, the Docker container, the dev process)
143 is torn down. Dev state never silently becomes cloud state.
144
145 ## Dev vs deploy
146
147 `alchemy dev` and `alchemy deploy` run the same stack into different
148 [stages](/environments/stages). Without `--stage`, dev uses
149 `dev_$USER` and deploy uses `live_$USER`, so a dev session never
150 touches what you deployed.
151
152 ```sh
153 alchemy dev # stage dev_sam
154 alchemy deploy # stage live_sam
155 ```
156
157 Every other command (`destroy`, `plan`, `logs`, `drift`) defaults to
158 the deploy stage. Pass `--stage` to point one at a dev stage.
159
160 ```sh
161 alchemy destroy # destroys live_sam
162 alchemy destroy --stage dev_sam # destroys your dev stage
163 ```
164
165 A dev stage is worth destroying. Resources with no local emulator,
166 and anything you pinned with `remote()`, are real cloud resources in
167 that stage. They keep running after you stop `alchemy dev`.
168
169 ### One dev stage per worktree
170
171 Every checkout on your machine shares `dev_$USER`, so two worktrees
172 running `alchemy dev` fight over one stage. See
173 [Worktrees](/environments/worktrees) to give each worktree its own
174 dev, deploy, and test stages.
175
176 ## Testing in dev mode
177
178 The [test harness](/testing/test-harness) runs the same suite
179 locally or live. Leave `dev` out of `Test.make` and the
180 `ALCHEMY_DEV` env var picks the mode:
181
182 ```sh
183 ALCHEMY_DEV=1 pnpm test # local emulators, no cloud calls
184 pnpm test # real cloud
185 ```
186
187 Iterate with the local run, and run live when you need the real
188 thing. A common split is local on pull requests and live on `main`:
189
190 ```yaml
191 # .github/workflows/test.yml
192 - run: pnpm test
193 env:
194 ALCHEMY_DEV: ${{ github.ref == 'refs/heads/main' && 'false' || 'true' }}
195 ```
196
197 See [Test harness → dev](/testing/test-harness#dev) for the option
198 itself.
199
200 ## Where next
201
202 - [Cloudflare local development](/cloudflare/local-development) — what runs in workerd and which bindings are simulated.
203 - [AWS local development](/aws/local-development) — the emulated AWS surface, Lambda/ECS containers, and zero-credential dev.
204 - [CI](/environments/ci) — deploy the same stack from GitHub Actions with PR previews.
205 - [Stages](/environments/stages) — how `live_$USER`, `dev_$USER`, `pr-42`, and `prod` stay isolated.
206 - [Dev servers](/command/dev-servers) — run any framework dev server as a `Command.Dev` resource in the dev loop.
207 - [Testing](/testing) — run the same test suite against the local emulators with `Test.make({ dev: true })`.
208 - [Local Providers](/infrastructure-as-code/local-provider) — build the local implementation of a resource.