1# Programmatic API
2 
3## Miniflare Class
4 
5```typescript
6class Miniflare {
7  constructor(options: MiniflareOptions);
8  
9  // Lifecycle
10  ready: Promise<URL>; // Resolves when server ready, returns URL
11  dispose(): Promise<void>; // Cleanup resources
12  setOptions(options: MiniflareOptions): Promise<void>; // Reload config
13  
14  // Event dispatching
15  dispatchFetch(url: string | URL | Request, init?: RequestInit): Promise<Response>;
16  getWorker(name?: string): Promise<Worker>;
17  
18  // Bindings access
19  getBindings<Bindings = Record<string, unknown>>(name?: string): Promise<Bindings>;
20  getCf(name?: string): Promise<IncomingRequestCfProperties | undefined>;
21  getKVNamespace(name: string): Promise<KVNamespace>;
22  getR2Bucket(name: string): Promise<R2Bucket>;
23  getDurableObjectNamespace(name: string): Promise<DurableObjectNamespace>;
24  getDurableObjectStorage(id: DurableObjectId): Promise<DurableObjectStorage>;
25  getD1Database(name: string): Promise<D1Database>;
26  getCaches(): Promise<CacheStorage>;
27  getQueueProducer(name: string): Promise<QueueProducer>;
28  
29  // Debugging
30  getInspectorURL(): Promise<URL>; // Chrome DevTools inspector URL
31}
32```
33 
34## Event Dispatching
35 
36**Fetch (no HTTP server):**
37```js
38const res = await mf.dispatchFetch("http://localhost:8787/path", {
39  method: "POST",
40  headers: { "Authorization": "Bearer token" },
41  body: JSON.stringify({ data: "value" }),
42});
43```
44 
45**Custom Host routing:**
46```js
47const res = await mf.dispatchFetch("http://localhost:8787/", {
48  headers: { "Host": "api.example.com" },
49});
50```
51 
52**Scheduled:**
53```js
54const worker = await mf.getWorker();
55const result = await worker.scheduled({ cron: "30 * * * *" });
56// result: { outcome: "ok", noRetry: false }
57```
58 
59**Queue:**
60```js
61const worker = await mf.getWorker();
62const result = await worker.queue("queue-name", [
63  { id: "msg1", timestamp: new Date(), body: "data", attempts: 1 },
64]);
65// result: { outcome: "ok", retryAll: false, ackAll: false, ... }
66```
67 
68## Bindings Access
69 
70**Environment variables:**
71```js
72// Basic usage
73const bindings = await mf.getBindings();
74console.log(bindings.SECRET_KEY);
75 
76// With type safety (recommended):
77interface Env {
78  SECRET_KEY: string;
79  API_URL: string;
80  KV: KVNamespace;
81}
82const env = await mf.getBindings<Env>();
83env.SECRET_KEY; // string (typed!)
84env.KV.get("key"); // KVNamespace methods available
85```
86 
87**Request.cf object:**
88```js
89const cf = await mf.getCf();
90console.log(cf?.colo); // "DFW"
91console.log(cf?.country); // "US"
92```
93 
94**KV:**
95```js
96const ns = await mf.getKVNamespace("TEST_NAMESPACE");
97await ns.put("key", "value");
98const value = await ns.get("key");
99```
100 
101**R2:**
102```js
103const bucket = await mf.getR2Bucket("BUCKET");
104await bucket.put("file.txt", "content");
105const object = await bucket.get("file.txt");
106```
107 
108**Durable Objects:**
109```js
110const ns = await mf.getDurableObjectNamespace("COUNTER");
111const id = ns.idFromName("test");
112const stub = ns.get(id);
113const res = await stub.fetch("http://localhost/");
114 
115// Access storage directly:
116const storage = await mf.getDurableObjectStorage(id);
117await storage.put("key", "value");
118```
119 
120**D1:**
121```js
122const db = await mf.getD1Database("DB");
123await db.exec(`CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)`);
124await db.prepare("INSERT INTO users (name) VALUES (?)").bind("Alice").run();
125```
126 
127**Cache:**
128```js
129const caches = await mf.getCaches();
130const defaultCache = caches.default;
131await defaultCache.put("http://example.com", new Response("cached"));
132```
133 
134**Queue producer:**
135```js
136const producer = await mf.getQueueProducer("QUEUE");
137await producer.send({ body: "message data" });
138```
139 
140## Lifecycle
141 
142**Reload:**
143```js
144await mf.setOptions({
145  scriptPath: "worker.js",
146  bindings: { VERSION: "2.0" },
147});
148```
149 
150**Watch (manual):**
151```js
152import { watch } from "fs";
153 
154const config = { scriptPath: "worker.js" };
155const mf = new Miniflare(config);
156 
157watch("worker.js", async () => {
158  console.log("Reloading...");
159  await mf.setOptions(config);
160});
161```
162 
163**Cleanup:**
164```js
165await mf.dispose();
166```
167 
168## Debugging
169 
170**Inspector URL for DevTools:**
171```js
172const url = await mf.getInspectorURL();
173console.log(`DevTools: ${url}`);
174// Open in Chrome DevTools for breakpoints, profiling
175```
176 
177**Wait for server ready:**
178```js
179const mf = new Miniflare({ scriptPath: "worker.js" });
180const url = await mf.ready; // Promise<URL>
181console.log(`Server running at ${url}`); // http://127.0.0.1:8787
182 
183// Note: dispatchFetch() waits automatically, no need to await ready
184const res = await mf.dispatchFetch("http://localhost/"); // Works immediately
185```
186 
187See [configuration.md](./configuration.md) for all constructor options.
188