1# Smart Placement Configuration
2 
3## wrangler.jsonc Setup
4 
5```jsonc
6{
7  "$schema": "./node_modules/wrangler/config-schema.json",
8  "placement": {
9    "mode": "smart"
10  }
11}
12```
13 
14## Placement Mode Values
15 
16| Mode | Behavior |
17|------|----------|
18| `"smart"` | Enable Smart Placement - automatic optimization based on traffic analysis |
19| `"off"` | Explicitly disable Smart Placement - always run at edge closest to user |
20| Not specified | Default behavior - run at edge closest to user (same as `"off"`) |
21 
22**Note:** Smart Placement vs Explicit Placement are separate features. Smart Placement (`mode: "smart"`) uses automatic analysis. For manual placement control, see explicit placement options (`region`, `host`, `hostname` fields - not covered in this reference).
23 
24## Frontend + Backend Split Configuration
25 
26### Frontend Worker (No Smart Placement)
27 
28```jsonc
29// frontend-worker/wrangler.jsonc
30{
31  "name": "frontend",
32  "main": "frontend-worker.ts",
33  // No "placement" - runs at edge
34  "services": [
35    {
36      "binding": "BACKEND",
37      "service": "backend-api"
38    }
39  ]
40}
41```
42 
43### Backend Worker (Smart Placement Enabled)
44 
45```jsonc
46// backend-api/wrangler.jsonc
47{
48  "name": "backend-api",
49  "main": "backend-worker.ts",
50  "placement": {
51    "mode": "smart"
52  },
53  "d1_databases": [
54    {
55      "binding": "DATABASE",
56      "database_id": "xxx"
57    }
58  ]
59}
60```
61 
62## Requirements & Limitations
63 
64### Requirements
65- **Wrangler version:** 2.20.0+
66- **Analysis time:** Up to 15 minutes
67- **Traffic requirements:** Consistent multi-location traffic
68- **Workers plan:** All plans (Free, Paid, Enterprise)
69 
70### What Smart Placement Affects
71 
72**CRITICAL LIMITATION - Smart Placement ONLY Affects `fetch` Handlers:**
73 
74Smart Placement is fundamentally limited to Workers with default `fetch` handlers. This is a key architectural constraint.
75 
76- ✅ **Affects:** `fetch` event handlers ONLY (the default export's fetch method)
77- ❌ **Does NOT affect:** 
78  - RPC methods (Service Bindings with `WorkerEntrypoint` - see example below)
79  - Named entrypoints (exports other than `default`)
80  - Workers without `fetch` handlers
81  - Queue consumers, scheduled handlers, or other event types
82 
83**Example - Smart Placement ONLY affects `fetch`:**
84```typescript
85// ✅ Smart Placement affects this:
86export default {
87  async fetch(request: Request, env: Env): Promise<Response> {
88    // This runs close to backend when Smart Placement enabled
89    const data = await env.DATABASE.prepare('SELECT * FROM users').all();
90    return Response.json(data);
91  }
92}
93 
94// ❌ Smart Placement DOES NOT affect these:
95export class MyRPC extends WorkerEntrypoint {
96  async myMethod() { 
97    // This ALWAYS runs at edge, Smart Placement has NO EFFECT
98    const data = await this.env.DATABASE.prepare('SELECT * FROM users').all();
99    return data;
100  }
101}
102 
103export async function scheduled(event: ScheduledEvent, env: Env) {
104  // NOT affected by Smart Placement
105}
106```
107 
108**Consequence:** If your backend logic uses RPC methods (`WorkerEntrypoint`), Smart Placement cannot optimize those calls. You must use fetch-based patterns for Smart Placement to work.
109 
110**Solution:** Convert RPC methods to fetch endpoints, or use a wrapper Worker with `fetch` handler that calls your backend RPC (though this adds latency).
111 
112### Baseline Traffic
113Smart Placement automatically routes 1% of requests WITHOUT optimization as baseline for performance comparison.
114 
115### Validation Rules
116 
117**Mutually exclusive fields:**
118- `mode` cannot be used with explicit placement fields (`region`, `host`, `hostname`)
119- Choose either Smart Placement OR explicit placement, not both
120 
121```jsonc
122// ✅ Valid - Smart Placement
123{ "placement": { "mode": "smart" } }
124 
125// ✅ Valid - Explicit Placement (different feature)
126{ "placement": { "region": "us-east1" } }
127 
128// ❌ Invalid - Cannot combine
129{ "placement": { "mode": "smart", "region": "us-east1" } }
130```
131 
132## Dashboard Configuration
133 
134**Workers & Pages** → Select Worker → **Settings** → **General** → **Placement: Smart** → Wait 15min → Check **Metrics**
135 
136## TypeScript Types
137 
138```typescript
139interface Env {
140  BACKEND: Fetcher;
141  DATABASE: D1Database;
142}
143 
144export default {
145  async fetch(request: Request, env: Env): Promise<Response> {
146    const data = await env.DATABASE.prepare('SELECT * FROM table').all();
147    return Response.json(data);
148  }
149} satisfies ExportedHandler<Env>;
150```
151 
152## Cloudflare Pages/Assets Warning
153 
154**CRITICAL PERFORMANCE ISSUE:** Enabling Smart Placement with `assets.run_worker_first = true` in Pages projects **severely degrades asset serving performance**. This is one of the most common misconfigurations.
155 
156**Why this is bad:**
157- Smart Placement routes ALL requests (including static assets) away from edge to remote locations
158- Static assets (HTML, CSS, JS, images) should ALWAYS be served from edge closest to user
159- Result: 2-5x slower asset loading times, poor user experience
160 
161**Problem:** Smart Placement routes asset requests away from edge, but static assets should always be served from edge closest to user.
162 
163**Solutions (in order of preference):**
1641. **Recommended:** Split into separate Workers (frontend at edge + backend with Smart Placement)
1652. Set `"mode": "off"` to explicitly disable Smart Placement for Pages/Assets Workers
1663. Use `assets.run_worker_first = false` (serves assets first, bypasses Worker for static content)
167 
168```jsonc
169// ❌ BAD - Degrades asset performance by 2-5x
170{
171  "name": "pages-app",
172  "placement": { "mode": "smart" },
173  "assets": { "run_worker_first": true }
174}
175 
176// ✅ GOOD - Frontend at edge, backend optimized
177// frontend-worker/wrangler.jsonc
178{
179  "name": "frontend",
180  "assets": { "run_worker_first": true }
181  // No placement - runs at edge
182}
183 
184// backend-worker/wrangler.jsonc
185{
186  "name": "backend-api",
187  "placement": { "mode": "smart" },
188  "d1_databases": [{ "binding": "DB", "database_id": "xxx" }]
189}
190```
191 
192**Key takeaway:** Never enable Smart Placement on Workers that serve static assets with `run_worker_first = true`.
193 
194## Local Development
195 
196Smart Placement does NOT work in `wrangler dev` (local only). Test by deploying: `wrangler deploy --env staging`
197