Skip to content
Cloudflare Docs

Local development

To test your Dispatch Worker, user Worker and Outbound Worker before deploying to production, you can use Wrangler for development and testing.

1. Create a user worker

Terminal window
npm create cloudflare@latest -- customer-worker-1

For setup, select the following options:

  • For What would you like to start with?, choose Hello World example.
  • For Which template would you like to use?, choose Worker only.
  • For Which language do you want to use?, choose JavaScript.
  • For Do you want to use git for version control?, choose Yes.
  • For Do you want to deploy your application?, choose No (we will be making some changes before deploying).

Then, move into the newly created directory:

Terminal window
cd customer-worker-1

Update the src/index.js file for customer-worker-1:

export default {
  async fetch(request) {
    // make a subrequest to the internet
    const response = await fetch("https://example.com");
    return new Response(
      `user worker got "${await response.text()}" from fetch`,
    );
  },
};

Update the Wrangler file for customer-worker-1 and add the dispatch namespace:

{
  "dispatch_namespace": "my-namespace"
}

2. Create a dispatch worker

Terminal window
npm create cloudflare@latest -- dispatch-worker

For setup, select the following options:

  • For What would you like to start with?, choose Hello World example.
  • For Which template would you like to use?, choose Worker only.
  • For Which language do you want to use?, choose JavaScript.
  • For Do you want to use git for version control?, choose Yes.
  • For Do you want to deploy your application?, choose No (we will be making some changes before deploying).

Then, move into the newly created directory:

Terminal window
cd dispatch-worker

Update the src/index.js file for dispatch-worker:

export default {
  async fetch(request, env) {
    // get the user Worker, specifying parameters that the Outbound Worker will see when it intercepts a user worker's subrequest
    const customerScript = env.DISPATCH_NAMESPACE.get(
      "customer-worker-1",
      {},
      {
        outbound: {
          paramCustomerName: "customer-1",
        },
      },
    );
    // invoke user Worker
    return await customerScript.fetch(request);
  },
};

Update the Wrangler file for dispatch-worker and add the dispatch namespace binding:

{
  "dispatch_namespaces": [
    {
      "binding": "DISPATCH_NAMESPACE",
      "namespace": "my-namespace",
      "outbound": {
        "service": "outbound-worker",
        "parameters": [
          "paramCustomerName"
        ]
      }
    }
  ]
}

3. Create an Outbound Worker

Terminal window
npm create cloudflare@latest -- outbound-worker

For setup, select the following options:

  • For What would you like to start with?, choose Hello World example.
  • For Which template would you like to use?, choose Worker only.
  • For Which language do you want to use?, choose JavaScript.
  • For Do you want to use git for version control?, choose Yes.
  • For Do you want to deploy your application?, choose No (we will be making some changes before deploying).

Then, move into the newly created directory:

Terminal window
cd outbound-worker

Update the src/index.js file for outbound-worker:

export default {
  async fetch(request, env) {
    const { paramCustomerName } = env;
    // use the parameters passed by the dispatcher to know what this user this request is for
    // and return custom content back to the user worker
    return new Response(
      `intercepted a request for ${paramCustomerName} by the outbound`,
    );
  },
};

4. Start local dev session for your Workers

In separate terminals, start a local dev session for each of your Workers.

For your dispatcher Worker:

Terminal window
cd dispatch-worker
npx wrangler@dispatch-namespaces-dev dev --port 8600

For your outbound Worker:

Terminal window
cd outbound-worker
npx wrangler@dispatch-namespaces-dev dev --port 8601

And for your user Worker:

Terminal window
cd customer-worker-1
npx wrangler@dispatch-namespaces-dev dev --port 8602

5. Test your requests

Send a request to your dispatcher Worker:

Terminal window
curl http://localhost:8600
# -> user worker got "intercepted a request for customer-1 by the outbound" from fetch

Remote dispatch namespaces

You can configure dispatch namespace bindings to connect to remote dispatch namespaces during local development by setting experimental_remote = true:

{
  "dispatch_namespaces": [
    {
      "binding": "DISPATCH_NAMESPACE",
      "namespace": "testing",
      "experimental_remote": true
    }
  ]
}

This allows you to run your dynamic dispatch Worker locally, while connecting it to your remote dispatch namespace binding. You can then test changes to your core dispatching logic against real, deployed user Workers.

For more information about remote bindings during local development, refer to remote bindings documentation.