1# Configuration
2 
3## wrangler.jsonc
4 
5```jsonc
6{
7  "name": "my-pages-project",
8  "pages_build_output_dir": "./dist",
9  "compatibility_date": "2026-01-01", // Use current date for new projects
10  "compatibility_flags": ["nodejs_compat"],
11  "placement": {
12    "mode": "smart"  // Optional: Enable Smart Placement
13  },
14  "kv_namespaces": [{"binding": "KV", "id": "abcd1234..."}],
15  "d1_databases": [{"binding": "DB", "database_id": "xxxx-xxxx", "database_name": "production-db"}],
16  "r2_buckets": [{"binding": "BUCKET", "bucket_name": "my-bucket"}],
17  "durable_objects": {"bindings": [{"name": "COUNTER", "class_name": "Counter", "script_name": "counter-worker"}]},
18  "services": [{"binding": "API", "service": "api-worker"}],
19  "queues": {"producers": [{"binding": "QUEUE", "queue": "my-queue"}]},
20  "vectorize": [{"binding": "VECTORIZE", "index_name": "my-index"}],
21  "ai": {"binding": "AI"},
22  "analytics_engine_datasets": [{"binding": "ANALYTICS"}],
23  "vars": {"API_URL": "https://api.example.com", "ENVIRONMENT": "production"},
24  "env": {
25    "preview": {
26      "vars": {"API_URL": "https://staging-api.example.com"},
27      "kv_namespaces": [{"binding": "KV", "id": "preview-namespace-id"}]
28    }
29  }
30}
31```
32 
33## Build Config
34 
35**Git deployment**: Dashboard → Project → Settings → Build settings  
36Set build command, output dir, env vars. Framework auto-detection configures automatically.
37 
38## Environment Variables
39 
40### Local (.dev.vars)
41```bash
42# .dev.vars (never commit)
43SECRET_KEY="local-secret-key"
44API_TOKEN="dev-token-123"
45```
46 
47### Production
48```bash
49echo "secret-value" | npx wrangler pages secret put SECRET_KEY --project-name=my-project
50npx wrangler pages secret list --project-name=my-project
51npx wrangler pages secret delete SECRET_KEY --project-name=my-project
52```
53 
54Access: `env.SECRET_KEY`
55 
56## Static Config Files
57 
58### _redirects
59Place in build output (e.g., `dist/_redirects`):
60 
61```txt
62/old-page /new-page 301          # 301 redirect
63/blog/* /news/:splat 301         # Splat wildcard
64/users/:id /members/:id 301      # Placeholders
65/api/* /api-v2/:splat 200        # Proxy (no redirect)
66```
67 
68**Limits**: 2,100 total (2,000 static + 100 dynamic), 1,000 char/line  
69**Note**: Functions take precedence
70 
71### _headers
72```txt
73/secure/*
74  X-Frame-Options: DENY
75  X-Content-Type-Options: nosniff
76 
77/api/*
78  Access-Control-Allow-Origin: *
79 
80/static/*
81  Cache-Control: public, max-age=31536000, immutable
82```
83 
84**Limits**: 100 rules, 2,000 char/line  
85**Note**: Only static assets; Functions set headers in Response
86 
87### _routes.json
88Controls which requests invoke Functions (auto-generated for most frameworks):
89 
90```json
91{
92  "version": 1,
93  "include": ["/*"],
94  "exclude": ["/build/*", "/static/*", "/assets/*", "/*.{ico,png,jpg,css,js}"]
95}
96```
97 
98**Purpose**: Functions are metered; static requests are free. `exclude` takes precedence. Max 100 rules, 100 char/rule.
99 
100## TypeScript
101 
102```bash
103npx wrangler types --path='./functions/types.d.ts'
104```
105 
106Point `types` in `functions/tsconfig.json` to generated file.
107 
108## Smart Placement
109 
110Automatically optimizes function execution location based on request patterns.
111 
112```jsonc
113{
114  "placement": {
115    "mode": "smart"  // Enable optimization (default: off)
116  }
117}
118```
119 
120**How it works**: System analyzes traffic over hours/days and places function execution closer to:
121- User clusters (e.g., regional traffic)
122- Data sources (e.g., D1 database primary location)
123 
124**Benefits**: 
125- Lower latency for read-heavy apps with centralized databases
126- Better performance for apps with regional traffic patterns
127 
128**Trade-offs**:
129- Initial learning period: First requests may be slower while system optimizes
130- Optimization time: Performance improves over 24-48 hours
131 
132**When to enable**: Global apps with D1/Durable Objects in specific regions, or apps with concentrated geographic traffic.
133 
134**When to skip**: Evenly distributed global traffic with no data locality constraints.
135 
136## Remote Bindings (Local Dev)
137 
138Connect local dev server to production bindings instead of local mocks:
139 
140```bash
141# All bindings remote
142npx wrangler pages dev ./dist --remote
143 
144# Specific bindings remote (others local)
145npx wrangler pages dev ./dist --remote --kv=KV --d1=DB
146```
147 
148**Use cases**:
149- Test against production data (read-only operations)
150- Debug binding-specific behavior
151- Validate changes before deployment
152 
153**⚠️ Warning**: 
154- Writes affect **real production data**
155- Use only for read-heavy debugging or with non-production accounts
156- Consider creating separate preview environments instead
157 
158**Requirements**: Must be logged in (`npx wrangler login`) with access to bindings.
159 
160## Local Dev
161 
162```bash
163# Basic
164npx wrangler pages dev ./dist
165 
166# With bindings
167npx wrangler pages dev ./dist --kv KV --d1 DB=local-db-id
168 
169# Remote bindings (production data)
170npx wrangler pages dev ./dist --remote
171 
172# Persistence
173npx wrangler pages dev ./dist --persist-to=./.wrangler/state/v3
174 
175# Proxy mode (SSR frameworks)
176npx wrangler pages dev -- npm run dev
177```
178 
179## Limits (as of Jan 2026)
180 
181| Resource | Free | Paid |
182|----------|------|------|
183| **Functions Requests** | 100k/day | Unlimited (metered) |
184| **Function CPU Time** | 10ms/req | 30s default, 5min max (Workers Paid) |
185| **Function Memory** | 128MB | 128MB |
186| **Script Size** | 1MB compressed | 10MB compressed |
187| **Deployments** | 500/month | 5,000/month |
188| **Files per Deploy** | 20,000 | 20,000 |
189| **File Size** | 25MB | 25MB |
190| **Build Time** | 20min | 20min |
191| **Redirects** | 2,100 (2k static + 100 dynamic) | Same |
192| **Header Rules** | 100 | 100 |
193| **Route Rules** | 100 | 100 |
194| **Subrequests** | 50/request | 10,000/request (Workers Paid) |
195 
196**Notes**:
197- Functions use Workers runtime; Workers Paid plan increases limits
198- Free plan sufficient for most projects
199- Static requests always free (not counted toward limits)
200 
201[Full limits](https://developers.cloudflare.com/pages/platform/limits/)
202