Miniflare

Local simulator for Cloudflare Workers development/testing. Runs Workers in workerd sandbox implementing runtime APIs - no internet required.

Features

Full-featured: KV, Durable Objects, R2, D1, WebSockets, Queues
Fully-local: test without internet, instant reload
TypeScript-native: detailed logging, source maps
Advanced testing: dispatch events without HTTP, simulate Worker connections

When to Use

Decision tree for testing Workers:

Need to test Workers?
│
├─ Unit tests for business logic only?
│  └─ getPlatformProxy (Vitest/Jest) → [patterns.md](./patterns.md#getplatformproxy)
│     Fast, no HTTP, direct binding access
│
├─ Integration tests with full runtime?
│  ├─ Single Worker?
│  │  └─ Miniflare API → [Quick Start](#quick-start)
│  │     Full control, programmatic access
│  │
│  ├─ Multiple Workers + service bindings?
│  │  └─ Miniflare workers array → [configuration.md](./configuration.md#multiple-workers)
│  │     Shared storage, inter-worker calls
│  │
│  └─ Vitest test runner integration?
│     └─ vitest-pool-workers → [patterns.md](./patterns.md#vitest-pool-workers)
│        Full Workers env in Vitest
│
└─ Local dev server?
   └─ wrangler dev (not Miniflare)
      Hot reload, automatic config

Use Miniflare for:

Integration tests with full Worker runtime
Testing bindings/storage locally
Multiple Workers with service bindings
Programmatic event dispatch (fetch, queue, scheduled)

Use getPlatformProxy for:

Fast unit tests of business logic
Testing without HTTP overhead
Vitest/Jest environments

Use Wrangler for:

Local development workflow
Production deployments

Setup

npm i -D miniflare

Requires ES modules in package.json:

{"type": "module"}

Quick Start

import { Miniflare } from "miniflare";

const mf = new Miniflare({
  modules: true,
  script: `
    export default {
      async fetch(request, env, ctx) {
        return new Response("Hello Miniflare!");
      }
    }
  `,
});

const res = await mf.dispatchFetch("http://localhost:8787/");
console.log(await res.text()); // Hello Miniflare!
await mf.dispose();

Reading Order

New to Miniflare? Start here:

Quick Start - Running in 2 minutes
When to Use - Choose your testing approach
patterns.md - Testing patterns (getPlatformProxy, Vitest, node:test)
configuration.md - Configure bindings, storage, multiple workers

Troubleshooting:

gotchas.md - Common errors and debugging

API reference:

api.md - Complete method reference

README.md