1# Miniflare
2 
3Local simulator for Cloudflare Workers development/testing. Runs Workers in workerd sandbox implementing runtime APIs - no internet required.
4 
5## Features
6 
7- Full-featured: KV, Durable Objects, R2, D1, WebSockets, Queues
8- Fully-local: test without internet, instant reload
9- TypeScript-native: detailed logging, source maps
10- Advanced testing: dispatch events without HTTP, simulate Worker connections
11 
12## When to Use
13 
14**Decision tree for testing Workers:**
15 
16```
17Need to test Workers?
18│
19├─ Unit tests for business logic only?
20│  └─ getPlatformProxy (Vitest/Jest) → [patterns.md](./patterns.md#getplatformproxy)
21│     Fast, no HTTP, direct binding access
22│
23├─ Integration tests with full runtime?
24│  ├─ Single Worker?
25│  │  └─ Miniflare API → [Quick Start](#quick-start)
26│  │     Full control, programmatic access
27│  │
28│  ├─ Multiple Workers + service bindings?
29│  │  └─ Miniflare workers array → [configuration.md](./configuration.md#multiple-workers)
30│  │     Shared storage, inter-worker calls
31│  │
32│  └─ Vitest test runner integration?
33│     └─ vitest-pool-workers → [patterns.md](./patterns.md#vitest-pool-workers)
34│        Full Workers env in Vitest
35│
36└─ Local dev server?
37   └─ wrangler dev (not Miniflare)
38      Hot reload, automatic config
39```
40 
41**Use Miniflare for:**
42- Integration tests with full Worker runtime
43- Testing bindings/storage locally
44- Multiple Workers with service bindings
45- Programmatic event dispatch (fetch, queue, scheduled)
46 
47**Use getPlatformProxy for:**
48- Fast unit tests of business logic
49- Testing without HTTP overhead
50- Vitest/Jest environments
51 
52**Use Wrangler for:**
53- Local development workflow
54- Production deployments
55 
56## Setup
57 
58```bash
59npm i -D miniflare
60```
61 
62Requires ES modules in `package.json`:
63```json
64{"type": "module"}
65```
66 
67## Quick Start
68 
69```js
70import { Miniflare } from "miniflare";
71 
72const mf = new Miniflare({
73  modules: true,
74  script: `
75    export default {
76      async fetch(request, env, ctx) {
77        return new Response("Hello Miniflare!");
78      }
79    }
80  `,
81});
82 
83const res = await mf.dispatchFetch("http://localhost:8787/");
84console.log(await res.text()); // Hello Miniflare!
85await mf.dispose();
86```
87 
88## Reading Order
89 
90**New to Miniflare?** Start here:
911. [Quick Start](#quick-start) - Running in 2 minutes
922. [When to Use](#when-to-use) - Choose your testing approach
933. [patterns.md](./patterns.md) - Testing patterns (getPlatformProxy, Vitest, node:test)
944. [configuration.md](./configuration.md) - Configure bindings, storage, multiple workers
95 
96**Troubleshooting:**
97- [gotchas.md](./gotchas.md) - Common errors and debugging
98 
99**API reference:**
100- [api.md](./api.md) - Complete method reference
101 
102## See Also
103- [wrangler](../wrangler/) - CLI tool that embeds Miniflare for `wrangler dev`
104- [workerd](../workerd/) - Runtime that powers Miniflare
105- [workers](../workers/) - Workers runtime API documentation
106