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
Section titled “How it works”alchemy dev✓ Bucket (Cloudflare.R2Bucket) created ✓ DB (Cloudflare.D1Database) created ✓ Worker (Cloudflare.Worker) created (local → workerd) • http://localhost:1337 Watching for changes ...
Three things happen:
- Infrastructure deploys to the cloud — R2 Buckets, D1 Databases, KV Namespaces are created on the real provider. No emulation, no fidelity gaps.
- 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.
- File changes hot reload — edit your code and the Worker rebuilds instantly.
Hot module reloading
Section titled “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
- Edit, save, refresh
Why not emulate everything?
Section titled “Why not emulate everything?”Full local emulation (Miniflare, LocalStack) replicates cloud APIs on your machine. This leads to fidelity gaps, missing features, and false confidence — tests pass locally but fail in production.
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
Section titled “Debugging”Because Workers run locally in workerd, you can attach a debugger:
- Set breakpoints in your IDE
- Inspect variables and call stacks
- Profile performance
No more console.log debugging against deployed Workers.
Resource adaptation
Section titled “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
Section titled “Custom port”export default Cloudflare.Worker("Worker", { main: import.meta.path, dev: { port: 3000, }, // ...});Dev vs Deploy
Section titled “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 |