Miniflare 3: Local Workers development on the real runtime

Miniflare 2 shipped earlier this year as a local simulator for Cloudflare Workers, bringing features like step-through debugging, source-mapped error pages, live reload and a configurable unit testing environment. It also underpinned wrangler dev --local. The catch: Miniflare 2 reimplemented Workers runtime APIs in JavaScript, and those reimplementations could drift from production behavior.

Subtle mismatches were hard to catch locally. A Worker that reads a response body created in a different request's handler, for example, would pass in Miniflare 2 but fail once deployed with Error: Cannot perform I/O on behalf of a different request. The runtime enforces that restriction deliberately to improve performance, but a simulator couldn't easily detect the violation. Miniflare 2 also ran on Node's V8 version, which sometimes lagged behind the JavaScript features supported by the Workers runtime, such as Array#findLast.

Miniflare 3 eliminates that gap by building on the open-sourced workerd runtime — the same code that runs on Cloudflare's network. That gives bug-for-bug compatibility with production and lets the team cut over 50,000 lines of code from the previous implementation while keeping the developer conveniences like live reload and detailed logging.

Local development against real data

One reason developers test on the Cloudflare network is to work against real data rather than fixtures that never quite match. Miniflare 3 introduces an experimental opt-in that reads and writes to namespaces on the Cloudflare network as if the Worker were deployed. For now this works with Workers KV; R2 and D1 access are being explored. Local reads and writes are cached so subsequent accesses in the same session stay fast.

Local becomes the default for wrangler dev

With accuracy essentially matching production and real-data access available locally, the Wrangler experience is shifting. In a future update, wrangler dev --local will become the default — no flag required. Early benchmarks point to roughly 10x faster startup and 60x faster script reloads. The Wrangler team plans to keep optimizing performance over the coming weeks.

Starting local projects from the dashboard

Developers who have built Workers in the Cloudflare dashboard can now migrate them to a local Wrangler project. With Node.js installed, running npx wrangler init --from-dash <your_worker_name> sets up a project with existing code and bindings such as KV namespaces configured. Deployment remains npx wrangler publish.

Roadmap

Automated testing is the next focus area. A preliminary API for programmatic end-to-end tests with wrangler dev already exists, and the team is investigating porting Miniflare 2's Jest and Vitest environments to workerd. IDE extensions to ease Worker development are also under consideration.

Miniflare 3.0 is already bundled in Wrangler. Try it with npx wrangler@latest dev --experimental-local, report issues via GitHub, and discuss in the #wrangler channel on the Cloudflare Developers Discord.