Workers Smart Placement -- Optimal Region Execution

In this tutorial, you'll learn about Workers Smart Placement. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

Cloudflare Workers Smart Placement is an intelligent routing feature that automatically selects the optimal edge data center for executing your Worker, minimizing latency by placing computation near the origin services your Worker depends on rather than near the end user.

Why Smart Placement Matters

By default, Workers run at the edge location closest to the user who made the request. This is ideal for serving static content or using Cloudflare storage products like KV and D1, which are globally replicated. However, many Workers act as proxies or orchestrators that call backend APIs, databases, or legacy systems running in specific regions. In these cases, running the Worker close to the user creates unnecessary latency -- the request must travel from the edge to the origin and back. Smart Placement solves this by running the Worker at the edge location closest to your backend origin, reducing round-trip time by 200-500 milliseconds for cross-continental requests. Unlike Cloudflare's standard routing which prioritizes the user's proximity, Smart Placement optimizes for the origin's proximity. This is especially valuable for Workers that make multiple backend calls or stream large responses from REST APIs.

Real-world use: A Worker authenticates users, then queries a PostgreSQL database hosted in Frankfurt. Without Smart Placement, a user in Tokyo triggers the Worker in Tokyo, which then calls Frankfurt -- a round trip of 250ms. With Smart Placement, the Worker runs in Frankfurt, reducing the database query to 2ms.

Smart Placement Architecture

flowchart TD
    subgraph Without_Smart_Placement
        U1[User in Tokyo] --> E1[Edge Tokyo]
        E1 --> O1[Origin in Frankfurt]
        O1 --> E1
        E1 --> U1
    end

    subgraph With_Smart_Placement
        U2[User in Tokyo] --> E2[Edge Tokyo]
        E2 --> E3[Edge Frankfurt *]
        E3 --> O2[Origin in Frankfurt]
        O2 --> E3
        E3 --> E2
        E2 --> U2
    end

    style E3 fill:#f90,color:#fff
    style O2 fill:#2ecc71,color:#fff
    style E1 fill:#e74c3c,color:#fff

Smart Placement learns from your Worker's traffic patterns. The first few requests may not be optimally placed, but as the system observes which origins your Worker calls, it migrates execution to the edge location with the lowest combined latency.

Enabling Smart Placement in wrangler.toml

# wrangler.toml
name = "smart-api-gateway"
main = "src/index.js"

[placement]
mode = "smart"

# Without placement config, the Worker runs near the user
# With mode = "smart", Cloudflare optimizes for origin proximity

# Alternatively, enable via the Cloudflare Dashboard:
# Workers & Pages -> Your Worker -> Settings -> Placement -> Smart
# Or use the API:
curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/scripts/smart-api-gateway" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"placement": {"mode": "smart"}}'

# Expected output:
# {"success": true, "result": {"placement": {"mode": "smart"}}

Enabling Smart Placement requires no code changes. Simply set [placement] mode = "smart" in wrangler.toml and redeploy. Cloudflare's placement algorithm automatically analyzes your Worker's outbound request destinations.

Smart Placement with Multiple Origins

export default {
  async fetch(request, env) {
    const url = new URL(request.url);

    // These outbound requests determine optimal placement
    if (url.pathname.startsWith('/users')) {
      const userResp = await fetch('https://api-users.eu.example.com/users');
      return new Response(await userResp.text());
    }

    if (url.pathname.startsWith('/orders')) {
      const orderResp = await fetch('https://api-orders.us.example.com/orders');
      return new Response(await orderResp.text());
    }

    // Mixed origins: Smart Placement finds the best compromise
    const [users, products] = await Promise.all([
      fetch('https://api-users.eu.example.com/stats'),
      fetch('https://api-products.us.example.com/stats')
    ]);

    const combined = {
      users: await users.json(),
      products: await products.json()
    };

    return new Response(JSON.stringify(combined), {
      headers: { 'Content-Type': 'application/json' }
    });
  }
};

// Expected behavior:
// If most requests go to EU origins, Smart Placement moves execution to EU edge
// If traffic patterns change, Smart Placement adapts within hours
// Logs show which placement Cloudflare chose:
// "Smart Placement chose location: frankfurt (FRA)"

Smart Placement considers all outbound fetch() calls your Worker makes. If your Worker calls multiple origins in different regions, the placement algorithm finds the optimal compromise based on traffic volume and latency.

Verifying Placement with Logs

export default {
  async fetch(request, env) {
    // Smart Placement adds the colo header after processing
    const response = await fetch('https://api-backend.example.com/data');

    // Clone to read headers
    const clonedResponse = new Response(response.body, response);

    // The CF-Ray header reveals which edge location handled the request
    const ray = clonedResponse.headers.get('CF-Ray');
    const placement = request.cf?.colo || 'unknown';

    console.log(`Request served from colo: ${placement}, Ray: ${ray}`);
    console.log(`Smart Placement active: ${request.cf?.placement || 'standard'}`);

    return clonedResponse;
  }
};

// Expected log output (with Smart Placement):
// Request served from colo: FRA, Ray: 7a3b5c8d1e2f3a4b
// Smart Placement active: smart
//
// Expected log output (without Smart Placement for same user):
// Request served from colo: NRT, Ray: 9f8e7d6c5b4a3f2e
// Smart Placement active: standard

You can verify Smart Placement is working by inspecting the request.cf.colo property, which shows the three-letter IATA code of the Cloudflare data center that executed your Worker. Compare with and without Smart Placement to measure the difference.

Common Errors

Practice Questions

1. What problem does Smart Placement solve that standard edge routing does not?
2. How do you enable Smart Placement in wrangler.toml?
3. How can you verify which edge location executed your Worker?

FAQ

Summary

Workers Smart Placement optimizes Worker execution location based on your backend origin's geography rather than the end user's location. Enable it with [placement] mode = "smart" in wrangler.toml with no code changes. The system learns your Worker's fetch patterns and migrates execution to the optimal edge data center, reducing latency for Workers that act as API gateways, proxy services, or backend orchestrators. Smart Placement is a zero-config performance optimization for Workers in the DodaTech infrastructure that call upstream services.

This guide is brought to you by the developers of Cloudflare, Serverless computing, and Durga Antivirus Pro at DodaTech.