Local development

alchemy dev gives you a fast local development loop without sacrificing access to real cloud services. Infrastructure is deployed to the cloud while your code runs locally with hot reloading.

How it works

alchemy dev

✓ Bucket (Cloudflare.R2.Bucket) created
✓ DB (Cloudflare.D1.Database) created
✓ Worker (Cloudflare.Worker) created (local → workerd)
  • http://localhost:1337

Watching for changes ...

Three things happen:

1. Infrastructure deploys to the cloud — R2 Buckets, D1 Databases, KV Namespaces are created on the real provider. No emulation, no fidelity gaps.
2. Workers run locally in workerd — your code executes in workerd, the same runtime used in production. A proxy routes requests between the cloud and your local process.
3. File changes hot reload — edit your code and the Worker rebuilds instantly.

dev deploys into your personal stage (dev_$USER by default), so your loop never collides with teammates or prod.

Hot module reloading

Watching for changes ...

↻ src/worker.ts changed
  • Rebuilding worker ...
✓ Worker reloaded in 42ms

↻ src/api.ts changed
  • Rebuilding worker ...
✓ Worker reloaded in 38ms

• Code changes take effect in milliseconds, not minutes
• Cloud resources stay deployed across reloads — only your application code is rebuilt

Arbitrary dev processes — Vite, Next, anything with a dev server — join the loop via Command.Dev: started by alchemy dev, restarted when its inputs change, and a no-op on deploy.

Why not emulate everything?

Full local emulation (Miniflare, LocalStack) replicates cloud APIs on your machine. This leads to fidelity gaps and missing features.

Alchemy avoids this. Your R2 Bucket is a real R2 Bucket. Your D1 Database is a real D1 Database. The only thing running locally is your application code.

Debugging

Because Workers run locally in workerd, you can attach a debugger:

• Set breakpoints in your IDE
• Inspect variables and call stacks
• Profile performance

Resource adaptation

Resources adapt their behavior in dev mode:

• Cloudflare Workers — run locally in workerd with a cloud proxy instead of deploying to the edge
• Vite dev servers — integrate with Alchemy’s dev server for frontend hot reloading alongside your backend
• Databases — connect to real cloud instances, eliminating schema drift between dev and prod

Each resource’s provider checks ALCHEMY_PHASE (set to dev) and adjusts accordingly.

Custom port

export default Cloudflare.Worker("Worker", {
  main: import.meta.url,
  dev: {
    port: 3000,
  },
  // ...
});

Dev vs Deploy

	alchemy dev	alchemy deploy
Infrastructure	Deployed to cloud	Deployed to cloud
Application code	Runs locally in workerd	Deployed to cloud
File watching	Hot reload on change	Manual redeploy
Debugging	Attach local debugger	Tail logs
Speed	Milliseconds	Seconds to minutes
Fidelity	Real cloud resources	Real cloud resources

To automate the deploy side, see the CI guide.

Where next

• CI — deploy the same stack from GitHub Actions with PR previews.
• Stages — how dev_$USER, pr-42, and prod stay isolated.
• Dev servers — run any framework dev server as a Command.Dev resource in the dev loop.