1# Wrangler Programmatic API
2 
3Node.js APIs for testing and development.
4 
5## startWorker (Testing)
6 
7Starts Worker with real local bindings for integration tests. Stable API (replaces `unstable_startWorker`).
8 
9```typescript
10import { startWorker } from "wrangler";
11import { describe, it, before, after } from "node:test";
12import assert from "node:assert";
13 
14describe("worker", () => {
15  let worker;
16  
17  before(async () => {
18    worker = await startWorker({
19      config: "wrangler.jsonc",
20      environment: "development"
21    });
22  });
23  
24  after(async () => {
25    await worker.dispose();
26  });
27  
28  it("responds with 200", async () => {
29    const response = await worker.fetch("http://example.com");
30    assert.strictEqual(response.status, 200);
31  });
32});
33```
34 
35### Options
36 
37| Option | Type | Description |
38|--------|------|-------------|
39| `config` | `string` | Path to wrangler.jsonc |
40| `environment` | `string` | Environment name from config |
41| `persist` | `boolean \| { path: string }` | Enable persistent state |
42| `bundle` | `boolean` | Enable bundling (default: true) |
43| `remote` | `false \| true \| "minimal"` | Remote mode: `false` (local), `true` (full remote), `"minimal"` (remote bindings only) |
44 
45### Remote Mode
46 
47```typescript
48// Local mode (default) - fast, simulated
49const worker = await startWorker({ config: "wrangler.jsonc" });
50 
51// Full remote mode - production-like, slower
52const worker = await startWorker({ 
53  config: "wrangler.jsonc",
54  remote: true 
55});
56 
57// Minimal remote mode - remote bindings, local Worker
58const worker = await startWorker({ 
59  config: "wrangler.jsonc",
60  remote: "minimal"
61});
62```
63 
64## getPlatformProxy
65 
66Emulate bindings in Node.js without starting Worker.
67 
68```typescript
69import { getPlatformProxy } from "wrangler";
70 
71const { env, dispose, caches } = await getPlatformProxy<Env>({
72  configPath: "wrangler.jsonc",
73  environment: "production",
74  persist: { path: ".wrangler/state" }
75});
76 
77// Use bindings
78const value = await env.MY_KV.get("key");
79await env.DB.prepare("SELECT * FROM users").all();
80await env.ASSETS.put("file.txt", "content");
81 
82// Platform APIs
83await caches.default.put("https://example.com", new Response("cached"));
84 
85await dispose();
86```
87 
88Use for unit tests (test functions, not full Worker) or scripts that need bindings.
89 
90## Type Generation
91 
92Generate types from config: `wrangler types` → creates `worker-configuration.d.ts`
93 
94## Event System
95 
96Listen to Worker lifecycle events for advanced workflows.
97 
98```typescript
99import { startWorker } from "wrangler";
100 
101const worker = await startWorker({
102  config: "wrangler.jsonc",
103  bundle: true
104});
105 
106// Bundle events
107worker.on("bundleStart", (details) => {
108  console.log("Bundling started:", details.config);
109});
110 
111worker.on("bundleComplete", (details) => {
112  console.log("Bundle ready:", details.duration);
113});
114 
115// Reconfiguration events
116worker.on("reloadStart", () => {
117  console.log("Worker reloading...");
118});
119 
120worker.on("reloadComplete", () => {
121  console.log("Worker reloaded");
122});
123 
124await worker.dispose();
125```
126 
127### Dynamic Reconfiguration
128 
129```typescript
130import { startWorker } from "wrangler";
131 
132const worker = await startWorker({ config: "wrangler.jsonc" });
133 
134// Replace entire config
135await worker.setConfig({
136  config: "wrangler.staging.jsonc",
137  environment: "staging"
138});
139 
140// Patch specific fields
141await worker.patchConfig({
142  vars: { DEBUG: "true" }
143});
144 
145await worker.dispose();
146```
147 
148## unstable_dev (Deprecated)
149 
150Use `startWorker` instead.
151 
152## Multi-Worker Registry
153 
154Test multiple Workers with service bindings.
155 
156```typescript
157import { startWorker } from "wrangler";
158 
159const auth = await startWorker({ config: "./auth/wrangler.jsonc" });
160const api = await startWorker({
161  config: "./api/wrangler.jsonc",
162  bindings: { AUTH: auth }  // Service binding
163});
164 
165const response = await api.fetch("http://example.com/api/login");
166// API Worker calls AUTH Worker via env.AUTH.fetch()
167 
168await api.dispose();
169await auth.dispose();
170```
171 
172## Best Practices
173 
174- Use `startWorker` for integration tests (tests full Worker)
175- Use `getPlatformProxy` for unit tests (tests individual functions)
176- Use `remote: true` when debugging production-specific issues
177- Use `remote: "minimal"` for faster tests with real bindings
178- Enable `persist: true` for debugging (state survives runs)
179- Run `wrangler types` after config changes
180- Always `dispose()` to prevent resource leaks
181- Listen to bundle events for build monitoring
182- Use multi-worker registry for testing service bindings
183 
184## See Also
185 
186- [README.md](./README.md) - CLI commands
187- [configuration.md](./configuration.md) - Config
188- [patterns.md](./patterns.md) - Testing patterns
189