1# Workers Configuration
2 
3## wrangler.jsonc (Recommended)
4 
5```jsonc
6{
7  "$schema": "./node_modules/wrangler/config-schema.json",
8  "name": "my-worker",
9  "main": "src/index.ts",
10  "compatibility_date": "2025-01-01", // Use current date for new projects
11  
12  // Bindings (non-inheritable)
13  "vars": { "ENVIRONMENT": "production" },
14  "kv_namespaces": [{ "binding": "MY_KV", "id": "abc123" }],
15  "r2_buckets": [{ "binding": "MY_BUCKET", "bucket_name": "my-bucket" }],
16  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "xyz789" }],
17  
18  // Environments
19  "env": {
20    "staging": {
21      "vars": { "ENVIRONMENT": "staging" },
22      "kv_namespaces": [{ "binding": "MY_KV", "id": "staging-id" }]
23    }
24  }
25}
26```
27 
28## Configuration Rules
29 
30**Inheritable**: `name`, `main`, `compatibility_date`, `routes`, `workers_dev`  
31**Non-inheritable**: All bindings (`vars`, `kv_namespaces`, `r2_buckets`, etc.)  
32**Top-level only**: `migrations`, `keep_vars`, `send_metrics`
33 
34**ALWAYS set `compatibility_date` to current date for new projects**
35 
36## Bindings
37 
38```jsonc
39{
40  // Environment variables - access via env.VAR_NAME
41  "vars": { "ENVIRONMENT": "production" },
42  
43  // KV (key-value storage)
44  "kv_namespaces": [{ "binding": "MY_KV", "id": "abc123" }],
45  
46  // R2 (object storage)
47  "r2_buckets": [{ "binding": "MY_BUCKET", "bucket_name": "my-bucket" }],
48  
49  // D1 (SQL database)
50  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "xyz789" }],
51  
52  // Durable Objects (stateful coordination)
53  "durable_objects": {
54    "bindings": [{ "name": "COUNTER", "class_name": "Counter" }]
55  },
56  
57  // Queues (message queues)
58  "queues": {
59    "producers": [{ "binding": "MY_QUEUE", "queue": "my-queue" }],
60    "consumers": [{ "queue": "my-queue", "max_batch_size": 10 }]
61  },
62  
63  // Service bindings (worker-to-worker RPC)
64  "services": [{ "binding": "SERVICE_B", "service": "service-b" }],
65  
66  // Analytics Engine
67  "analytics_engine_datasets": [{ "binding": "ANALYTICS" }]
68}
69```
70 
71### Secrets
72 
73Set via CLI (never in config):
74 
75```bash
76npx wrangler secret put API_KEY
77```
78 
79Access: `env.API_KEY`
80 
81### Automatic Provisioning (Beta)
82 
83Bindings without IDs are auto-created:
84 
85```jsonc
86{ "kv_namespaces": [{ "binding": "MY_KV" }] }  // ID added on deploy
87```
88 
89## Routes & Triggers
90 
91```jsonc
92{
93  "routes": [
94    { "pattern": "example.com/*", "zone_name": "example.com" }
95  ],
96  "triggers": {
97    "crons": ["0 */6 * * *"]  // Every 6 hours
98  }
99}
100```
101 
102## TypeScript Setup
103 
104### Automatic Type Generation (Recommended)
105 
106```bash
107npm install -D @cloudflare/workers-types
108npx wrangler types  # Generates .wrangler/types/runtime.d.ts from wrangler.jsonc
109```
110 
111`tsconfig.json`:
112 
113```jsonc
114{
115  "compilerOptions": {
116    "target": "ES2022",
117    "lib": ["ES2022"],
118    "types": ["@cloudflare/workers-types"]
119  },
120  "include": [".wrangler/types/**/*.ts", "src/**/*"]
121}
122```
123 
124Import generated types:
125 
126```typescript
127import type { Env } from './.wrangler/types/runtime';
128 
129export default {
130  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
131    await env.MY_KV.get('key');  // Fully typed, autocomplete works
132    return new Response('OK');
133  },
134};
135```
136 
137Re-run `npx wrangler types` after changing bindings in wrangler.jsonc
138 
139### Manual Type Definition (Legacy)
140 
141```typescript
142interface Env {
143  MY_KV: KVNamespace;
144  DB: D1Database;
145  API_KEY: string;
146}
147```
148 
149## Advanced Options
150 
151```jsonc
152{
153  // Auto-locate compute near data sources
154  "placement": { "mode": "smart" },
155  
156  // Enable Node.js built-ins (Buffer, process, path, etc.)
157  "compatibility_flags": ["nodejs_compat"],
158  
159  // Observability (10% sampling)
160  "observability": { "enabled": true, "head_sampling_rate": 0.1 }
161}
162```
163 
164### Node.js Compatibility
165 
166`nodejs_compat` enables:
167- `Buffer`, `process.env`, `path`, `stream`
168- CommonJS `require()` for Node modules
169- `node:` imports (e.g., `import { Buffer } from 'node:buffer'`)
170 
171**Note:** Adds ~1-2ms cold start overhead. Use Workers APIs (R2, KV) when possible
172 
173## Deployment Commands
174 
175```bash
176npx wrangler deploy              # Production
177npx wrangler deploy --env staging
178npx wrangler deploy --dry-run    # Validate only
179```
180 
181## See Also
182 
183- [API](./api.md) - Runtime APIs and bindings usage
184- [Patterns](./patterns.md) - Deployment strategies
185- [Wrangler](../wrangler/README.md) - CLI reference
186