Skip to content
Cloudflare Docs

Create a dynamic dispatch Worker

A dynamic dispatch Worker is a specialized routing Worker that directs incoming requests to the appropriate user Workers in your dispatch namespace. Instead of using Workers Routes, dispatch Workers let you programmatically control request routing through code.

Figure 1: Workers for Platforms: Main Flow

Why use a dynamic dispatch Worker?

  • Scale: Allows you to route requests to millions of hostnames to different Workers, without defining Workers Routes configuration for each one
  • Custom routing logic: Write code to determine exactly how requests should be routed. For example:
    • Store hostname-to-Worker mappings in Workers KV and look them up dynamically
    • Route requests based on subdomain, path, headers, or other request properties
    • Use custom metadata attached to custom hostnames ↗ for routing decisions

Configure the dispatch namespace binding

To allow your dynamic dispatch Worker to dynamically route requests to Workers in a namespace, you need to configure a dispatch namespace binding. This binding enables your dynamic dispatch Worker to call any user Worker within that namespace using env.dispatcher.get().

{
  "dispatch_namespaces": [
    {
      "binding": "DISPATCHER",
      "namespace": "my-dispatch-namespace"
    }
  ]
}

Once the binding is configured, your dynamic dispatch Worker can route requests to any Worker in the namespace. Below are common routing patterns you can implement in your dispatcher.

Routing examples

Figure 2: Workers for Platforms: Main Flow

KV-Based Routing

Store the routing mappings in Workers KV. This allows you to modify your routing logic without requiring you to change or redeploy the dynamic dispatch Worker.

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


      // Use hostname, path, or any combination as the routing key
      const routingKey = url.hostname;


      // Lookup user Worker name from KV store
      const userWorkerName = await env.USER_ROUTING.get(routingKey);


      if (!userWorkerName) {
        return new Response('Route not configured', { status: 404 });
      }


      // Optional: Cache the KV lookup result
      const userWorker = env.DISPATCHER.get(userWorkerName);
      return await userWorker.fetch(request);
    } catch (e) {
      if (e.message.startsWith('Worker not found')) {
        return new Response('', { status: 404 });
      }
      return new Response(e.message, { status: 500 });
    }
  }
};

Subdomain-Based Routing

Route subdomains to the corresponding Worker. For example, my-customer.example.com will route to the Worker named my-customer in the dispatch namespace.

export default {
  async fetch(request, env) {
    try {
      // Extract user Worker name from subdomain
      // Example: customer1.example.com -> customer1
      const url = new URL(request.url);
      const userWorkerName = url.hostname.split('.')[0];


      // Get user Worker from dispatch namespace
      const userWorker = env.DISPATCHER.get(userWorkerName);
      return await userWorker.fetch(request);
    } catch (e) {
      if (e.message.startsWith('Worker not found')) {
        // User Worker doesn't exist in dispatch namespace
        return new Response('', { status: 404 });
      }
      // Could be any other exception from fetch() or from the dispatched Worker
      return new Response(e.message, { status: 500 });
    }
  }
};

Path-Based routing

Route URL paths to the corresponding Worker. For example, example.com/customer-1 will route to the Worker named customer-1 in the dispatch namespace.

export default {
  async fetch(request, env) {
    try {
      const url = new URL(request.url);
      const pathParts = url.pathname.split('/').filter(Boolean);


      if (pathParts.length === 0) {
        return new Response('Invalid path', { status: 400 });
      }


      // example.com/customer-1 -> routes to 'customer-1' worker
      const userWorkerName = pathParts[0];


      const userWorker = env.DISPATCHER.get(userWorkerName);
      return await userWorker.fetch(request);
    } catch (e) {
      if (e.message.startsWith('Worker not found')) {
        return new Response('', { status: 404 });
      }
      return new Response(e.message, { status: 500 });
    }
  }
};