1# Workerd Patterns
2 
3## Multi-Service Architecture
4```capnp
5const config :Workerd.Config = (
6  services = [
7    (name = "frontend", worker = (
8      modules = [(name = "index.js", esModule = embed "frontend/index.js")],
9      compatibilityDate = "2024-01-15",
10      bindings = [(name = "API", service = "api")]
11    )),
12    (name = "api", worker = (
13      modules = [(name = "index.js", esModule = embed "api/index.js")],
14      compatibilityDate = "2024-01-15",
15      bindings = [(name = "DB", service = "postgres"), (name = "CACHE", kvNamespace = "kv")]
16    )),
17    (name = "postgres", external = (address = "db.internal:5432", http = ())),
18    (name = "kv", disk = (path = "/var/kv", writable = true))
19  ],
20  sockets = [(name = "http", address = "*:8080", http = (), service = "frontend")]
21);
22```
23 
24## Durable Objects
25```capnp
26const worker :Workerd.Worker = (
27  modules = [(name = "index.js", esModule = embed "index.js"), (name = "room.js", esModule = embed "room.js")],
28  compatibilityDate = "2024-01-15",
29  bindings = [(name = "ROOMS", durableObjectNamespace = "Room")],
30  durableObjectNamespaces = [(className = "Room", uniqueKey = "v1")],
31  durableObjectStorage = (localDisk = "/var/do")
32);
33```
34 
35## Dev vs Prod Configs
36```capnp
37# Use parameter bindings for env-specific config
38const baseWorker :Workerd.Worker = (
39  modules = [(name = "index.js", esModule = embed "src/index.js")],
40  compatibilityDate = "2024-01-15",
41  bindings = [(name = "API_URL", parameter = (type = text))]
42);
43 
44const prodWorker :Workerd.Worker = (
45  inherit = "base-service",
46  bindings = [(name = "API_URL", text = "https://api.prod.com")]
47);
48```
49 
50## HTTP Reverse Proxy
51```capnp
52services = [
53  (name = "proxy", worker = (serviceWorkerScript = embed "proxy.js", compatibilityDate = "2024-01-15", bindings = [(name = "BACKEND", service = "backend")])),
54  (name = "backend", external = (address = "internal:8080", http = ()))
55]
56```
57 
58## Local Development
59 
60**Recommended:** Use Wrangler
61```bash
62wrangler dev  # Uses workerd internally
63```
64 
65**Direct workerd:**
66```bash
67workerd serve config.capnp --socket-addr http=*:3000 --verbose
68```
69 
70**Environment variables:**
71```capnp
72bindings = [(name = "DATABASE_URL", fromEnvironment = "DATABASE_URL")]
73```
74 
75## Testing
76```bash
77workerd test config.capnp
78workerd test config.capnp --test-only=test.js
79```
80 
81Test files must be included in `modules = [...]` config.
82 
83## Production Deployment
84 
85### Compiled Binary (Recommended)
86```bash
87workerd compile config.capnp myConfig -o production-server
88./production-server
89```
90 
91### Docker
92```dockerfile
93FROM debian:bookworm-slim
94RUN apt-get update && apt-get install -y ca-certificates
95COPY workerd /usr/local/bin/
96COPY config.capnp /etc/workerd/
97COPY src/ /etc/workerd/src/
98EXPOSE 8080
99CMD ["workerd", "serve", "/etc/workerd/config.capnp"]
100```
101 
102### Systemd
103```ini
104# /etc/systemd/system/workerd.service
105[Service]
106ExecStart=/usr/bin/workerd serve /etc/workerd/config.capnp --socket-fd http=3
107Restart=always
108User=nobody
109```
110 
111See systemd socket activation docs for complete setup.
112 
113## Framework Integration
114 
115### Hono
116```javascript
117import { Hono } from 'hono';
118 
119const app = new Hono();
120 
121app.get('/', (c) => c.text('Hello Hono!'));
122app.get('/api/:id', async (c) => {
123  const id = c.req.param('id');
124  const data = await c.env.KV.get(id);
125  return c.json({ id, data });
126});
127 
128export default app;
129```
130 
131### itty-router
132```javascript
133import { Router } from 'itty-router';
134 
135const router = Router();
136 
137router.get('/', () => new Response('Hello itty!'));
138router.get('/api/:id', async (request, env) => {
139  const { id } = request.params;
140  const data = await env.KV.get(id);
141  return Response.json({ id, data });
142});
143 
144export default {
145  fetch: (request, env, ctx) => router.handle(request, env, ctx)
146};
147```
148 
149## Best Practices
150 
1511. **Use ES modules** over service worker syntax
1522. **Explicit bindings** - no global namespace assumptions
1533. **Type safety** - define `Env` interfaces (use `wrangler types`)
1544. **Service isolation** - split concerns into multiple services
1555. **Pin compat date** in production after testing
1566. **Use ctx.waitUntil()** for background tasks
1577. **Handle errors gracefully** with try/catch
1588. **Configure resource limits** on caches/storage
159 
160## Common Patterns
161 
162### Error Handling
163```javascript
164export default {
165  async fetch(request, env, ctx) {
166    try {
167      return await handleRequest(request, env);
168    } catch (error) {
169      console.error("Request failed", error);
170      return new Response("Internal Error", {status: 500});
171    }
172  }
173};
174```
175 
176### Background Tasks
177```javascript
178export default {
179  async fetch(request, env, ctx) {
180    const response = new Response("OK");
181    
182    // Fire-and-forget background work
183    ctx.waitUntil(
184      env.ANALYTICS.put(request.url, Date.now())
185    );
186    
187    return response;
188  }
189};
190```
191 
192See [configuration.md](./configuration.md) for config syntax, [api.md](./api.md) for runtime APIs, [gotchas.md](./gotchas.md) for common errors.
193