README

Smart 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.

When to Use

Enable Smart Placement when:

• Worker makes multiple round trips to backend services/databases
• Backend infrastructure is geographically concentrated
• Request duration dominated by backend latency rather than network latency from user
• Running backend logic in Workers (APIs, data aggregation, SSR with DB calls)
• Worker uses fetch handler (not RPC methods)

Do NOT enable for:

• Workers serving only static content or cached responses
• Workers without significant backend communication
• Pure edge logic (auth checks, redirects, simple transformations)
• Workers without fetch event handlers
• Workers with RPC methods or named entrypoints (only fetch handlers are affected)
• Pages/Assets Workers with run_worker_first = true (degrades asset serving)

Decision Tree

Key Architecture Pattern

Recommended: Split full-stack applications into separate Workers:

This maintains fast, reactive frontends while optimizing backend latency.

Quick Start

Deploy and wait 15 minutes for analysis. Check status via API or dashboard metrics.

To disable: Set "mode": "off" or remove placement field entirely (both equivalent).

Requirements

• Wrangler 2.20.0+
• Analysis time: Up to 15 minutes after enabling
• Traffic requirements: Consistent traffic from multiple global locations
• Available on all Workers plans (Free, Paid, Enterprise)

Placement Status Values

CLI Commands

Reading Order

First time? Start here:

1. This README - understand core concepts and when to use Smart Placement
2. configuration.md - set up wrangler.jsonc and understand limitations
3. patterns.md - see practical examples for your use case
4. api.md - monitor and verify Smart Placement is working
5. gotchas.md - troubleshoot common issues

Quick lookup:

• “Should I enable Smart Placement?” → See “When to Use” above
• “How do I configure it?” → configuration.md
• “How do I split frontend/backend?” → patterns.md
• “Why isn’t it working?” → gotchas.md

In This Reference

• configuration.md - wrangler.jsonc setup, mode values, validation rules
• api.md - Placement Status API, cf-placement header, monitoring
• patterns.md - Frontend/backend split, database workers, SSR patterns
• gotchas.md - Troubleshooting INSUFFICIENT_INVOCATIONS, performance issues

See Also

• workers (opens in a new tab) - Worker runtime and fetch handlers
• d1 (opens in a new tab) - D1 database that benefits from Smart Placement
• durable-objects (opens in a new tab) - Durable Objects with backend logic
• bindings (opens in a new tab) - Service bindings for frontend/backend split