clover's git

the-knife

1	---
2	title: "Part 4: Local Dev"
3	description: Run your stack locally with alchemy dev for hot reloading and instant feedback.
4	sidebar:
5	order: 4
6	---
7
8	In [Part 3](/cloudflare/tutorial/part-3) you wrote integration tests against
9	your deployed stack. But deploying to Cloudflare on every code change
10	is slow. In this part you'll use `bun alchemy dev` to run everything
11	locally with hot reloading.
12
13	## Start dev mode
14
15	```sh
16	bun alchemy dev
17	```
18
19	That's it. Alchemy deploys your stack to the cloud and proxies
20	requests to Workers running locally in workerd. It watches for file
21	changes and hot reloads your Worker automatically.
22
23	Your Worker is available at `http://localhost:1337` by default:
24
25	```sh
26	curl http://localhost:1337/hello.txt
27	```
28
29	## How it works
30
31	`bun alchemy dev` does three things:
32
33	1. **Deploys to the cloud** — resources like R2 Buckets are created
34	on Cloudflare, while Workers run locally in workerd
35	2. **Watches for changes** — when you edit `src/worker.ts` or any
36	file it imports, the Worker is rebuilt and reloaded instantly
37	3. **Preserves local state** — data in your local R2 Bucket persists
38	across restarts
39
40	The same `alchemy.run.ts` is used for both `dev` and `deploy` — no
41	separate dev config needed.
42
43	## Custom port
44
45	Set a custom port for your Worker:
46
47	```diff lang="typescript"
48	// src/worker.ts
49	export default Cloudflare.Worker(
50	"Worker",
51	{
52	main: import.meta.url,
53	+ dev: {
54	+ port: 3000,
55	+ },
56	},
57	// ...
58	);
59	```
60
61	## Run tests in dev mode
62
63	You don't need to run `bun alchemy dev` in a separate terminal to test
64	against locally-emulated resources. The test harness has its own
65	`dev` flag that flips every Worker over to workerd inside the test
66	process — same wiring as `bun alchemy dev`, no extra terminal.
67
68	```diff lang="typescript"
69	// test/integ.test.ts
70	const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
71	providers: Cloudflare.providers(),
72	state: Cloudflare.state(),
73	+ dev: true,
74	});
75	```
76
77	`beforeAll(deploy(Stack))` now boots the Workers locally; HTTP
78	assertions hit `http://localhost:1337` and roundtrip into your code
79	with full stack traces.
80
81	## Toggle dev mode from CI
82
83	Hardcoding `dev: true` would force CI runs to local emulation too.
84	Read it from the environment instead so the same test file runs
85	against real cloud resources in CI and locally-emulated ones on your
86	laptop.
87
88	```diff lang="typescript"
89	const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
90	providers: Cloudflare.providers(),
91	state: Cloudflare.state(),
92	- dev: true,
93	});
94	```
95
96	Drop the explicit flag and the harness falls back to the
97	`ALCHEMY_DEV` env var — set `ALCHEMY_DEV=1` in your shell to flip
98	to local mode, leave it unset in CI.
99
100	```sh
101	ALCHEMY_DEV=1 bun test test/integ.test.ts
102	```
103
104	## Recap
105
106	You now have:
107
108	- Local development with `bun alchemy dev`
109	- Hot reloading on file changes
110	- Local emulation of Cloudflare resources
111
112	In [Part 5](/cloudflare/tutorial/part-5), you'll set up GitHub Actions for
113	automated deployments and PR preview environments.