1# Wrangler Configuration
2 
3Configuration reference for wrangler.jsonc (recommended).
4 
5## Config Format
6 
7**wrangler.jsonc recommended** (Wrangler v4+) - provides schema validation.
8 
9```jsonc
10{
11  "$schema": "./node_modules/wrangler/config-schema.json",
12  "name": "my-worker",
13  "main": "src/index.ts",
14  "compatibility_date": "2025-01-01",  // Use current date
15  "vars": { "API_KEY": "dev-key" },
16  "kv_namespaces": [{ "binding": "MY_KV", "id": "abc123" }]
17}
18```
19 
20## Field Inheritance
21 
22Inheritable: `name`, `main`, `compatibility_date`, `routes`, `triggers`
23Non-inheritable (define per env): `vars`, bindings (KV, D1, R2, etc.)
24 
25## Environments
26 
27```jsonc
28{
29  "name": "my-worker",
30  "vars": { "ENV": "dev" },
31  "env": {
32    "production": {
33      "name": "my-worker-prod",
34      "vars": { "ENV": "prod" },
35      "route": { "pattern": "example.com/*", "zone_name": "example.com" }
36    }
37  }
38}
39```
40 
41Deploy: `wrangler deploy --env production`
42 
43## Routing
44 
45```jsonc
46// Custom domain (recommended)
47{ "routes": [{ "pattern": "api.example.com", "custom_domain": true }] }
48 
49// Zone-based
50{ "routes": [{ "pattern": "api.example.com/*", "zone_name": "example.com" }] }
51 
52// workers.dev
53{ "workers_dev": true }
54```
55 
56## Bindings
57 
58```jsonc
59// Variables
60{ "vars": { "API_URL": "https://api.example.com" } }
61 
62// KV
63{ "kv_namespaces": [{ "binding": "CACHE", "id": "abc123" }] }
64 
65// D1
66{ "d1_databases": [{ "binding": "DB", "database_id": "abc-123" }] }
67 
68// R2
69{ "r2_buckets": [{ "binding": "ASSETS", "bucket_name": "my-assets" }] }
70 
71// Durable Objects
72{ "durable_objects": { 
73  "bindings": [{ 
74    "name": "COUNTER", 
75    "class_name": "Counter",
76    "script_name": "my-worker"  // Required for external DOs
77  }] 
78} }
79{ "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Counter"] }] }
80 
81// Service Bindings
82{ "services": [{ "binding": "AUTH", "service": "auth-worker" }] }
83 
84// Queues
85{ "queues": {
86  "producers": [{ "binding": "TASKS", "queue": "task-queue" }],
87  "consumers": [{ "queue": "task-queue", "max_batch_size": 10 }]
88} }
89 
90// Vectorize
91{ "vectorize": [{ "binding": "VECTORS", "index_name": "embeddings" }] }
92 
93// Hyperdrive (requires nodejs_compat for pg/postgres)
94{ "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "hyper-id" }] }
95{ "compatibility_flags": ["nodejs_compat"] }  // For pg/postgres
96 
97// Workers AI
98{ "ai": { "binding": "AI" } }
99 
100// Workflows
101{ "workflows": [{ "binding": "WORKFLOW", "name": "my-workflow", "class_name": "MyWorkflow" }] }
102 
103// Secrets Store (centralized secrets)
104{ "secrets_store": [{ "binding": "SECRETS", "id": "store-id" }] }
105 
106// Constellation (AI inference)
107{ "constellation": [{ "binding": "MODEL", "project_id": "proj-id" }] }
108```
109 
110## Workers Assets (Static Files)
111 
112Recommended for serving static files (replaces old `site` config).
113 
114```jsonc
115{
116  "assets": {
117    "directory": "./public",
118    "binding": "ASSETS",
119    "html_handling": "auto-trailing-slash",  // or "none", "force-trailing-slash"
120    "not_found_handling": "single-page-application"  // or "404-page", "none"
121  }
122}
123```
124 
125Access in Worker:
126```typescript
127export default {
128  async fetch(request, env) {
129    // Try serving static asset first
130    const asset = await env.ASSETS.fetch(request);
131    if (asset.status !== 404) return asset;
132    
133    // Custom logic for non-assets
134    return new Response("API response");
135  }
136}
137```
138 
139## Placement
140 
141Control where Workers run geographically.
142 
143```jsonc
144{
145  "placement": {
146    "mode": "smart"  // or "off"
147  }
148}
149```
150 
151- `"smart"`: Run Worker near data sources (D1, Durable Objects) to reduce latency
152- `"off"`: Default distribution (run everywhere)
153 
154## Auto-Provisioning (Beta)
155 
156Omit resource IDs - Wrangler creates them and writes back to config on deploy.
157 
158```jsonc
159{ "kv_namespaces": [{ "binding": "MY_KV" }] }  // No id - auto-provisioned
160```
161 
162After deploy, ID is added to config automatically.
163 
164## Advanced
165 
166```jsonc
167// Cron Triggers
168{ "triggers": { "crons": ["0 0 * * *"] } }
169 
170// Observability (tracing)
171{ "observability": { "enabled": true, "head_sampling_rate": 0.1 } }
172 
173// Runtime Limits
174{ "limits": { "cpu_ms": 100 } }
175 
176// Browser Rendering
177{ "browser": { "binding": "BROWSER" } }
178 
179// mTLS Certificates
180{ "mtls_certificates": [{ "binding": "CERT", "certificate_id": "cert-uuid" }] }
181 
182// Logpush (stream logs to R2/S3)
183{ "logpush": true }
184 
185// Tail Consumers (process logs with another Worker)
186{ "tail_consumers": [{ "service": "log-worker" }] }
187 
188// Unsafe bindings (access to arbitrary bindings)
189{ "unsafe": { "bindings": [{ "name": "MY_BINDING", "type": "plain_text", "text": "value" }] } }
190```
191 
192## See Also
193 
194- [README.md](./README.md) - Overview and commands
195- [api.md](./api.md) - Programmatic API
196- [patterns.md](./patterns.md) - Workflows
197- [gotchas.md](./gotchas.md) - Common issues
198