1# Cloudflare Workers Smart Placement
2 
3Automatic workload placement optimization to minimize latency by running Workers closer to backend infrastructure rather than end users.
4 
5## Core Concept
6 
7Smart Placement automatically analyzes Worker request duration across Cloudflare's global network and intelligently routes requests to optimal data center locations. Instead of defaulting to the location closest to the end user, Smart Placement can forward requests to locations closer to backend infrastructure when this reduces overall request duration.
8 
9### When to Use
10 
11**Enable Smart Placement when:**
12- Worker makes multiple round trips to backend services/databases
13- Backend infrastructure is geographically concentrated
14- Request duration dominated by backend latency rather than network latency from user
15- Running backend logic in Workers (APIs, data aggregation, SSR with DB calls)
16- Worker uses `fetch` handler (not RPC methods)
17 
18**Do NOT enable for:**
19- Workers serving only static content or cached responses
20- Workers without significant backend communication
21- Pure edge logic (auth checks, redirects, simple transformations)
22- Workers without fetch event handlers
23- Workers with RPC methods or named entrypoints (only `fetch` handlers are affected)
24- Pages/Assets Workers with `run_worker_first = true` (degrades asset serving)
25 
26### Decision Tree
27 
28```
29Does your Worker have a fetch handler?
30├─ No → Smart Placement won't work (skip)
31└─ Yes
32   │
33   Does it make multiple backend calls (DB/API)?
34   ├─ No → Don't enable (won't help)
35   └─ Yes
36      │
37      Is backend geographically concentrated?
38      ├─ No (globally distributed) → Probably won't help
39      └─ Yes or uncertain
40         │
41         Does it serve static assets with run_worker_first=true?
42         ├─ Yes → Don't enable (will hurt performance)
43         └─ No → Enable Smart Placement
44            │
45            After 15min, check placement_status
46            ├─ SUCCESS → Monitor metrics
47            ├─ INSUFFICIENT_INVOCATIONS → Need more traffic
48            └─ UNSUPPORTED_APPLICATION → Disable (hurting performance)
49```
50 
51### Key Architecture Pattern
52 
53**Recommended:** Split full-stack applications into separate Workers:
54```
55User → Frontend Worker (at edge, close to user)
56         ↓ Service Binding
57       Backend Worker (Smart Placement enabled, close to DB/API)
58         ↓
59       Database/Backend Service
60```
61 
62This maintains fast, reactive frontends while optimizing backend latency.
63 
64## Quick Start
65 
66```jsonc
67// wrangler.jsonc
68{
69  "placement": {
70    "mode": "smart"  // or "off" to explicitly disable
71  }
72}
73```
74 
75Deploy and wait 15 minutes for analysis. Check status via API or dashboard metrics.
76 
77**To disable:** Set `"mode": "off"` or remove `placement` field entirely (both equivalent).
78 
79## Requirements
80 
81- Wrangler 2.20.0+
82- Analysis time: Up to 15 minutes after enabling
83- Traffic requirements: Consistent traffic from multiple global locations
84- Available on all Workers plans (Free, Paid, Enterprise)
85 
86## Placement Status Values
87 
88```typescript
89type PlacementStatus = 
90  | undefined  // Not yet analyzed
91  | 'SUCCESS'  // Successfully optimized
92  | 'INSUFFICIENT_INVOCATIONS'  // Not enough traffic
93  | 'UNSUPPORTED_APPLICATION';  // Made Worker slower (reverted)
94```
95 
96## CLI Commands
97 
98```bash
99# Deploy with Smart Placement
100wrangler deploy
101 
102# Check placement status
103curl -H "Authorization: Bearer $TOKEN" \
104  https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/services/$WORKER_NAME \
105  | jq .result.placement_status
106 
107# Monitor
108wrangler tail your-worker-name --header cf-placement
109```
110 
111## Reading Order
112 
113**First time?** Start here:
1141. This README - understand core concepts and when to use Smart Placement
1152. [configuration.md](./configuration.md) - set up wrangler.jsonc and understand limitations
1163. [patterns.md](./patterns.md) - see practical examples for your use case
1174. [api.md](./api.md) - monitor and verify Smart Placement is working
1185. [gotchas.md](./gotchas.md) - troubleshoot common issues
119 
120**Quick lookup:**
121- "Should I enable Smart Placement?" → See "When to Use" above
122- "How do I configure it?" → [configuration.md](./configuration.md)
123- "How do I split frontend/backend?" → [patterns.md](./patterns.md)
124- "Why isn't it working?" → [gotchas.md](./gotchas.md)
125 
126## In This Reference
127 
128- [configuration.md](./configuration.md) - wrangler.jsonc setup, mode values, validation rules
129- [api.md](./api.md) - Placement Status API, cf-placement header, monitoring
130- [patterns.md](./patterns.md) - Frontend/backend split, database workers, SSR patterns
131- [gotchas.md](./gotchas.md) - Troubleshooting INSUFFICIENT_INVOCATIONS, performance issues
132 
133## See Also
134 
135- [workers](../workers/) - Worker runtime and fetch handlers
136- [d1](../d1/) - D1 database that benefits from Smart Placement
137- [durable-objects](../durable-objects/) - Durable Objects with backend logic
138- [bindings](../bindings/) - Service bindings for frontend/backend split
139