1# Wrangler Development Patterns
2 
3Common workflows and best practices.
4 
5## New Worker Project
6 
7```bash
8wrangler init my-worker && cd my-worker
9wrangler dev              # Develop locally
10wrangler deploy           # Deploy
11```
12 
13## Local Development
14 
15```bash
16wrangler dev              # Local mode (fast, simulated)
17wrangler dev --remote     # Remote mode (production-accurate)
18wrangler dev --env staging --port 8787
19wrangler dev --inspector-port 9229  # Enable debugging
20```
21 
22Debug: chrome://inspect → Configure → localhost:9229
23 
24## Secrets
25 
26```bash
27# Production
28echo "secret-value" | wrangler secret put SECRET_KEY
29 
30# Local: use .dev.vars (gitignored)
31# SECRET_KEY=local-dev-key
32```
33 
34## Adding KV
35 
36```bash
37wrangler kv namespace create MY_KV
38wrangler kv namespace create MY_KV --preview
39# Add to wrangler.jsonc: { "binding": "MY_KV", "id": "abc123" }
40wrangler deploy
41```
42 
43## Adding D1
44 
45```bash
46wrangler d1 create my-db
47wrangler d1 migrations create my-db "initial_schema"
48# Edit migration file in migrations/, then:
49wrangler d1 migrations apply my-db --local
50wrangler deploy
51wrangler d1 migrations apply my-db --remote
52 
53# Time Travel (restore to point in time)
54wrangler d1 time-travel restore my-db --timestamp 2025-01-01T12:00:00Z
55```
56 
57## Multi-Environment
58 
59```bash
60wrangler deploy --env staging
61wrangler deploy --env production
62```
63 
64```jsonc
65{ "env": { "staging": { "vars": { "ENV": "staging" } } } }
66```
67 
68## Testing
69 
70### Integration Tests with Node.js Test Runner
71 
72```typescript
73import { startWorker } from "wrangler";
74import { describe, it, before, after } from "node:test";
75import assert from "node:assert";
76 
77describe("API", () => {
78  let worker;
79  
80  before(async () => {
81    worker = await startWorker({ 
82      config: "wrangler.jsonc",
83      remote: "minimal"  // Fast tests with real bindings
84    });
85  });
86  
87  after(async () => await worker.dispose());
88  
89  it("creates user", async () => {
90    const response = await worker.fetch("http://example.com/api/users", {
91      method: "POST",
92      body: JSON.stringify({ name: "Alice" })
93    });
94    assert.strictEqual(response.status, 201);
95  });
96});
97```
98 
99### Testing with Vitest
100 
101Install: `npm install -D vitest @cloudflare/vitest-pool-workers`
102 
103**vitest.config.ts:**
104```typescript
105import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
106export default defineWorkersConfig({
107  test: { poolOptions: { workers: { wrangler: { configPath: "./wrangler.jsonc" } } } }
108});
109```
110 
111**tests/api.test.ts:**
112```typescript
113import { env, SELF } from "cloudflare:test";
114import { describe, it, expect } from "vitest";
115 
116it("fetches users", async () => {
117  const response = await SELF.fetch("https://example.com/api/users");
118  expect(response.status).toBe(200);
119});
120 
121it("uses bindings", async () => {
122  await env.MY_KV.put("key", "value");
123  expect(await env.MY_KV.get("key")).toBe("value");
124});
125```
126 
127### Multi-Worker Development (Service Bindings)
128 
129```typescript
130const authWorker = await startWorker({ config: "./auth/wrangler.jsonc" });
131const apiWorker = await startWorker({
132  config: "./api/wrangler.jsonc",
133  bindings: { AUTH: authWorker }  // Service binding
134});
135 
136// Test API calling AUTH
137const response = await apiWorker.fetch("http://example.com/api/protected");
138await authWorker.dispose();
139await apiWorker.dispose();
140```
141 
142### Mock External APIs
143 
144```typescript
145const worker = await startWorker({ 
146  config: "wrangler.jsonc",
147  outboundService: (req) => {
148    const url = new URL(req.url);
149    if (url.hostname === "api.external.com") {
150      return new Response(JSON.stringify({ mocked: true }), {
151        headers: { "content-type": "application/json" }
152      });
153    }
154    return fetch(req);  // Pass through other requests
155  }
156});
157 
158// Test Worker that calls external API
159const response = await worker.fetch("http://example.com/proxy");
160// Worker internally fetches api.external.com - gets mocked response
161```
162 
163## Monitoring & Versions
164 
165```bash
166wrangler tail                 # Real-time logs
167wrangler tail --status error  # Filter errors
168wrangler versions list
169wrangler rollback [id]
170```
171 
172## TypeScript
173 
174```bash
175wrangler types  # Generate types from config
176```
177 
178```typescript
179export default {
180  async fetch(request: Request, env: Env): Promise<Response> {
181    return Response.json({ value: await env.MY_KV.get("key") });
182  }
183} satisfies ExportedHandler<Env>;
184```
185 
186## Workers Assets
187 
188```jsonc
189{ "assets": { "directory": "./dist", "binding": "ASSETS" } }
190```
191 
192```typescript
193export default {
194  async fetch(request, env) {
195    // API routes first
196    if (new URL(request.url).pathname.startsWith("/api/")) {
197      return Response.json({ data: "from API" });
198    }
199    return env.ASSETS.fetch(request);  // Static assets
200  }
201}
202```
203 
204## See Also
205 
206- [README.md](./README.md) - Commands
207- [configuration.md](./configuration.md) - Config
208- [api.md](./api.md) - Programmatic API
209- [gotchas.md](./gotchas.md) - Issues
210