1# Configuration
2 
3## TypeScript Setup
4 
5**Generate types from wrangler.jsonc** (replaces deprecated `@cloudflare/workers-types`):
6 
7```bash
8npx wrangler types
9```
10 
11Creates `worker-configuration.d.ts` with typed `Env` interface based on your bindings.
12 
13```typescript
14// functions/api.ts
15export const onRequest: PagesFunction<Env> = async (ctx) => {
16  // ctx.env.KV, ctx.env.DB, etc. are fully typed
17  return Response.json({ ok: true });
18};
19```
20 
21**Manual types** (if not using wrangler types):
22 
23```typescript
24interface Env {
25  KV: KVNamespace;
26  DB: D1Database;
27  API_KEY: string;
28}
29export const onRequest: PagesFunction<Env> = async (ctx) => { /* ... */ };
30```
31 
32## wrangler.jsonc
33 
34```jsonc
35{
36  "$schema": "./node_modules/wrangler/config-schema.json",
37  "name": "my-pages-app",
38  "pages_build_output_dir": "./dist",
39  "compatibility_date": "2025-01-01",
40  "compatibility_flags": ["nodejs_compat"],
41  
42  "vars": { "API_URL": "https://api.example.com" },
43  "kv_namespaces": [{ "binding": "KV", "id": "abc123" }],
44  "d1_databases": [{ "binding": "DB", "database_name": "prod-db", "database_id": "xyz789" }],
45  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "my-bucket" }],
46  "durable_objects": { "bindings": [{ "name": "COUNTER", "class_name": "Counter", "script_name": "counter-worker" }] },
47  "services": [{ "binding": "AUTH", "service": "auth-worker" }],
48  "ai": { "binding": "AI" },
49  "vectorize": [{ "binding": "VECTORIZE", "index_name": "my-index" }],
50  "analytics_engine_datasets": [{ "binding": "ANALYTICS" }]
51}
52```
53 
54## Environment Overrides
55 
56Top-level → local dev, `env.preview` → preview, `env.production` → production
57 
58```jsonc
59{
60  "vars": { "API_URL": "http://localhost:8787" },
61  "env": {
62    "production": { "vars": { "API_URL": "https://api.example.com" } }
63  }
64}
65```
66 
67**Note:** If overriding `vars`, `kv_namespaces`, `d1_databases`, etc., ALL must be redefined (non-inheritable)
68 
69## Local Secrets (.dev.vars)
70 
71**Local dev only** - NOT deployed:
72 
73```bash
74# .dev.vars (add to .gitignore)
75SECRET_KEY="my-secret-value"
76```
77 
78Accessed via `ctx.env.SECRET_KEY`. Set production secrets:
79```bash
80echo "value" | npx wrangler pages secret put SECRET_KEY --project-name=my-app
81```
82 
83## Static Config Files
84 
85**_routes.json** - Custom routing:
86```json
87{ "version": 1, "include": ["/api/*"], "exclude": ["/static/*"] }
88```
89 
90**_headers** - Static headers:
91```
92/static/*
93  Cache-Control: public, max-age=31536000
94```
95 
96**_redirects** - Redirects:
97```
98/old  /new  301
99```
100 
101## Local Dev & Deployment
102 
103```bash
104# Dev server
105npx wrangler pages dev ./dist
106 
107# With bindings
108npx wrangler pages dev ./dist --kv=KV --d1=DB=db-id --r2=BUCKET
109 
110# Durable Objects (2 terminals)
111cd do-worker && npx wrangler dev
112cd pages-project && npx wrangler pages dev ./dist --do COUNTER=Counter@do-worker
113 
114# Deploy
115npx wrangler pages deploy ./dist
116npx wrangler pages deploy ./dist --branch preview
117 
118# Download config
119npx wrangler pages download config my-project
120```
121 
122**See also:** [api.md](./api.md) for binding usage examples
123