1# Workerd Configuration
2 
3## Basic Structure
4```capnp
5using Workerd = import "/workerd/workerd.capnp";
6 
7const config :Workerd.Config = (
8  services = [(name = "main", worker = .mainWorker)],
9  sockets = [(name = "http", address = "*:8080", http = (), service = "main")]
10);
11 
12const mainWorker :Workerd.Worker = (
13  modules = [(name = "index.js", esModule = embed "src/index.js")],
14  compatibilityDate = "2024-01-15",
15  bindings = [...]
16);
17```
18 
19## Services
20**Worker**: Run JS/Wasm code
21```capnp
22(name = "api", worker = (
23  modules = [(name = "index.js", esModule = embed "index.js")],
24  compatibilityDate = "2024-01-15",
25  bindings = [...]
26))
27```
28 
29**Network**: Internet access
30```capnp
31(name = "internet", network = (allow = ["public"], tlsOptions = (trustBrowserCas = true)))
32```
33 
34**External**: Reverse proxy
35```capnp
36(name = "backend", external = (address = "api.com:443", http = (style = tls)))
37```
38 
39**Disk**: Static files
40```capnp
41(name = "assets", disk = (path = "/var/www", writable = false))
42```
43 
44## Sockets
45```capnp
46(name = "http", address = "*:8080", http = (), service = "main")
47(name = "https", address = "*:443", https = (options = (), tlsOptions = (keypair = (...))), service = "main")
48(name = "app", address = "unix:/tmp/app.sock", http = (), service = "main")
49```
50 
51## Worker Formats
52```capnp
53# ES Modules (recommended)
54modules = [(name = "index.js", esModule = embed "src/index.js"), (name = "wasm.wasm", wasm = embed "build/module.wasm")]
55 
56# Service Worker (legacy)
57serviceWorkerScript = embed "worker.js"
58 
59# CommonJS
60(name = "legacy.js", commonJsModule = embed "legacy.js", namedExports = ["foo"])
61```
62 
63## Bindings
64Bindings expose resources to workers. ES modules: `env.BINDING`, Service workers: globals.
65 
66### Primitive Types
67```capnp
68(name = "API_KEY", text = "secret")                    # String
69(name = "CONFIG", json = '{"key":"val"}')              # Parsed JSON
70(name = "DATA", data = embed "data.bin")               # ArrayBuffer
71(name = "DATABASE_URL", fromEnvironment = "DB_URL")    # System env var
72```
73 
74### Service Binding
75```capnp
76(name = "AUTH", service = "auth-worker")               # Basic
77(name = "API", service = (
78  name = "backend",
79  entrypoint = "adminApi",                             # Named export
80  props = (json = '{"role":"admin"}')                  # ctx.props
81))
82```
83 
84### Storage
85```capnp
86(name = "CACHE", kvNamespace = "kv-service")           # KV
87(name = "STORAGE", r2Bucket = "r2-service")            # R2
88(name = "ROOMS", durableObjectNamespace = (
89  serviceName = "room-service",
90  className = "Room"
91))
92(name = "FAST", memoryCache = (
93  id = "cache-id",
94  limits = (maxKeys = 1000, maxValueSize = 1048576)
95))
96```
97 
98### Other
99```capnp
100(name = "TASKS", queue = "queue-service")
101(name = "ANALYTICS", analyticsEngine = "analytics")
102(name = "LOADER", workerLoader = (id = "dynamic"))
103(name = "KEY", cryptoKey = (format = raw, algorithm = (name = "HMAC", hash = "SHA-256"), keyData = embed "key.bin", usages = [sign, verify], extractable = false))
104(name = "TRACED", wrapped = (moduleName = "tracing", entrypoint = "makeTracer", innerBindings = [(name = "backend", service = "backend")]))
105```
106 
107## Compatibility
108```capnp
109compatibilityDate = "2024-01-15"                       # Always set!
110compatibilityFlags = ["nodejs_compat", "streams_enable_constructors"]
111```
112 
113Version = max compat date. Update carefully after testing.
114 
115## Parameter Bindings (Inheritance)
116```capnp
117const base :Workerd.Worker = (
118  modules = [...], compatibilityDate = "2024-01-15",
119  bindings = [(name = "API_URL", parameter = (type = text)), (name = "DB", parameter = (type = service))]
120);
121 
122const derived :Workerd.Worker = (
123  inherit = "base-service",
124  bindings = [(name = "API_URL", text = "https://api.com"), (name = "DB", service = "postgres")]
125);
126```
127 
128## Durable Objects Config
129```capnp
130const worker :Workerd.Worker = (
131  modules = [...],
132  compatibilityDate = "2024-01-15",
133  bindings = [(name = "ROOMS", durableObjectNamespace = "Room")],
134  durableObjectNamespaces = [(className = "Room", uniqueKey = "v1")],
135  durableObjectStorage = (localDisk = "/var/do")
136);
137```
138 
139## Remote Bindings (Development)
140 
141Connect local workerd to production Cloudflare resources:
142 
143```capnp
144bindings = [
145  # Remote KV (requires API token)
146  (name = "PROD_KV", kvNamespace = (
147    remote = (
148      accountId = "your-account-id",
149      namespaceId = "your-namespace-id",
150      apiToken = .envVar("CF_API_TOKEN")
151    )
152  )),
153  
154  # Remote R2
155  (name = "PROD_R2", r2Bucket = (
156    remote = (
157      accountId = "your-account-id",
158      bucketName = "my-bucket",
159      apiToken = .envVar("CF_API_TOKEN")
160    )
161  )),
162  
163  # Remote Durable Object
164  (name = "PROD_DO", durableObjectNamespace = (
165    remote = (
166      accountId = "your-account-id",
167      scriptName = "my-worker",
168      className = "MyDO",
169      apiToken = .envVar("CF_API_TOKEN")
170    )
171  ))
172]
173```
174 
175**Note:** Remote bindings require network access and valid Cloudflare API credentials.
176 
177## Logging & Debugging
178```capnp
179logging = (structuredLogging = true, stdoutPrefix = "OUT: ", stderrPrefix = "ERR: ")
180v8Flags = ["--expose-gc", "--max-old-space-size=2048"]  # ⚠️ Unsupported in production
181```
182 
183See [patterns.md](./patterns.md) for multi-service examples, [gotchas.md](./gotchas.md) for config errors.
184