05 — Wrangler, Miniflare, and the Local Dev Loop

"Just deploy it and pray" was my Workers deployment ritual, until the local tooling turned out to be the same runtime as production. The model that changed it: the entire development lifecycle is owned by one CLI, Wrangler, and the local simulator it drives (Miniflare) runs the exact same workerd runtime that production does — so "works on my machine" actually means "works in production" here. [1][2] That tightness is the whole reason the dev loop feels different from every other serverless platform I've used.

The framing that landed is the symmetry. In most serverless setups, the local emulator is a different runtime than production — different quirks, different APIs, behaviors that pass locally and fail deployed. With Workers, Wrangler runs Miniflare, Miniflare runs workerd, and workerd _is_ the production runtime, open-sourced [3]. The thing my code executes against on localhost:8787 is the same binary my code executes against on the edge. The dev loop is short because there's nothing to translate.

Wrangler: the one CLI

Wrangler owns the entire lifecycle, and almost everything I do with Workers goes through it [1]. The commands I use constantly:

• wrangler init — scaffold a new project (TypeScript or JavaScript, with sensible defaults).
• wrangler dev — run the Worker locally against Miniflare, with hot reload.
• wrangler deploy — push to the edge.
• wrangler tail — stream real-time logs from a deployed Worker.
• wrangler secret put / wrangler kv key put — manage secrets and KV data without putting them in code.
• wrangler d1 execute, wrangler r2 object put — interact with the storage products from the command line.

Configuration lives in wrangler.toml (or .json/.js), which declares the Worker's name, entry point, compatibility date, and all its bindings — KV namespaces, R2 buckets, D1 databases, service bindings. The config file _is_ the source of truth for what the Worker can talk to [1]. Wrangler reads it for local dev and ships it on deploy.

Miniflare: the local runtime

Miniflare is the local simulator, and the key fact about it is that it's not an approximation — it runs workerd, the actual open-source Workers runtime [2][3]. That means every binding, every runtime API, every quirk I might depend on behaves locally the way it behaves in production.

The features I lean on:

• Faithful binding simulation. KV namespaces, Durable Objects, R2 buckets, Queues, D1 databases, Cache API — all work locally against an in-memory or on-disk stand-in. I can develop a stateful Worker end-to-end without deploying.
• Hot reload. Code changes are picked up on save, the Worker restarts in milliseconds, and I see the result on the next request.
• Source maps and stack traces. Errors point at the actual line in my source, not the bundled output.
• Deterministic testing. Because the local runtime is faithful, integration tests written against Miniflare have a high correlation with production behavior.

Miniflare is now built into Wrangler 3+, so I don't usually invoke it directly — wrangler dev drives it for me. It's worth knowing it exists because it explains _why_ local development is so reliable here.

DevTools and debugging

The debugging story has two layers [4]:

• Local DevTools. wrangler dev exposes a Chrome DevTools endpoint. I can open chrome://inspect, attach to the Worker, set breakpoints, inspect variables, step through execution — the full browser-debugging experience, applied to server code.
• Production observability. On the edge I don't have a debugger, but I have wrangler tail for live logs, Cloudflare's dashboard analytics for metrics, and source maps that make deployed stack traces readable.

The habit that pays off: develop against wrangler dev with DevTools until the logic is solid, then deploy and rely on structured console.log output streamed through wrangler tail for the inevitable production-only issues (real traffic patterns, real upstream APIs, real edge locations).

CI/CD pipelines

The thing that surprised me is how little specialized tooling CI/CD needs. A Workers deployment pipeline is, at its core, four lines in a GitHub Action [5]:

- uses: actions/checkout@v4
- uses: cloudflare/wrangler-action@v3
  with:
    apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    command: deploy

That's it. Wrangler handles the rest — bundling, the upload, the routing. GitLab CI, CircleCI, Travis CI all work the same way: install Wrangler, run wrangler deploy with a token [5]. The patterns worth adding on top are the same as any pipeline: lint and test before deploy, gate production deploys behind a manual approval, use environments for staging-vs-production config, and store the API token as a CI secret — never in code.

The decision of _when_ to deploy is the interesting part, not the mechanics. Trunk-based teams deploy on every push to main; release-based teams deploy on tags. Workers' fast, atomic deploys (and instant rollbacks via wrangler rollback) make trunk-based deploy-on-push realistic in a way it isn't on slower platforms.

How I use this

The dev loop I've settled on: wrangler dev running in a terminal, DevTools attached, a wrangler.toml checked into the repo with all bindings declared, secrets in wrangler secret, and a GitHub Action that runs wrangler deploy on every merge to main. Rollback is one command if something breaks. The whole loop — edit, save, see the result locally, push, have it live on the edge — is measured in seconds, and that speed is the thing that actually shapes how confidently I can ship.

References

[1] Cloudflare, "Wrangler documentation," Cloudflare Workers Docs, 2024. [Online]. Available: https://developers.cloudflare.com/workers/wrangler/

[2] Cloudflare, "Miniflare - Cloudflare Workers," Cloudflare Docs, 2024. [Online]. Available: https://developers.cloudflare.com/workers/testing/miniflare/

[3] Cloudflare, "Introducing workerd: the open source Workers runtime," Cloudflare Blog, 2022. [Online]. Available: https://blog.cloudflare.com/workerd-open-source-workers-runtime/

[4] Cloudflare, "Debugging Cloudflare Workers," Cloudflare Workers Playground Docs. [Online]. Available: https://developers.cloudflare.com/workers/playground/#devtools

[5] GitHub, "GitHub Actions — Automate your workflow," 2024. [Online]. Available: https://github.com/features/actions