Multi Workers development

When building complex applications, you may need to run multiple Workers during development. This guide covers the different approaches for running multiple Workers locally and when to use each approach.

Single dev session

You can run multiple Workers in a single dev session by passing multiple configuration files to your dev server.

1. Create separate configuration files for each Worker:

   Primary Worker

   wrangler.jsonc

   {
     "name": "app-worker",
     "main": "./src/index.ts",
     "services": [
       {
         "binding": "API",
         "service": "api-worker"
       }
     ]
   }

   wrangler.toml

   name = "app-worker"
   main = "./src/index.ts"
   
   [[services]]
   binding = "API"
   service = "api-worker"

   Auxiliary Worker

   wrangler.jsonc

   {
     "name": "api-worker",
     "main": "./src/index.ts"
   }

   wrangler.toml

   name = "api-worker"
   main = "./src/index.ts"

2. Start a dev session:

   Using Wrangler

   npm

   npx wrangler dev -c wrangler.jsonc -c ../api/wrangler.jsonc

   yarn

   yarn wrangler dev -c wrangler.jsonc -c ../api/wrangler.jsonc

   pnpm

   pnpm wrangler dev -c wrangler.jsonc -c ../api/wrangler.jsonc

   The first config is treated as the primary Worker, exposed at http://localhost:8787. Additional configs run as auxiliary Workers, available via service bindings or tail consumers from the primary Worker.

   Using the Vite plugin

   Configure auxiliaryWorkers in your Vite configuration:

   vite.config.js

   import { defineConfig } from "vite";
   import { cloudflare } from "@cloudflare/vite-plugin";
   
   export default defineConfig({
     plugins: [
       cloudflare({
         configPath: "./wrangler.jsonc",
         auxiliaryWorkers: [
           {
             configPath: "../api/wrangler.jsonc",
           },
         ],
       }),
     ],
   });

   Then run:

   npm

   npx vite dev

   yarn

   yarn vite dev

   pnpm

   pnpm vite dev

Use this approach when:

• Workers are closely related or part of the same application
• You want the simplest development setup
• You need to access a Durable Object namespace from another Worker using script_name

Multiple dev sessions

You can also run each Worker in a separate dev session, each with its own terminal and configuration.

# Terminal 1
wrangler dev

# Terminal 2
wrangler dev

These Workers run in different dev sessions but can still communicate with each other via service bindings or tail consumers regardless they are started with wrangler dev or vite dev.

Use this approach when:

• Each Worker uses a different build configuration
• Different teams maintain the Workers
• A Worker only occasionally accesses another, and you prefer the flexibility to run them separately

While this setup offers flexibility, there are some limitations to be aware of when using bindings across Workers running in separate dev sessions:

Bindings	Wrangler (single config)	Wrangler (multi config)	Vite (no auxiliaryWorkers)	Vite (with auxiliaryWorkers)
Service Bindings	✅	🔜	✅	✅
Durable Objects	⚠️	❌	❌	❌
Tail Consumers	✅	🔜	✅	✅

✅ = Full support. ⚠️ = Fetch only. RPC is not supported. 🔜 = No support yet. Coming soon. ❌ = Not supported.

Hybrid approach

You can also combine both approaches — for example, run a group of Workers together through vite dev using auxiliaryWorkers, while running another Worker separately with wrangler dev.

# Terminal 1
vite dev

# Terminal 2
wrangler dev

This allows you to keep tightly coupled Workers in a single dev session, while treating independent or shared Workers as separate sessions.

Use this approach when:

• You have an independent Worker that is shared across multiple applications
• You are integrating with a legacy Worker that you don't want to refactor yet
• Your project structure benefits from the flexibility of both approaches

The same limitations for bindings apply when Workers are run across multiple dev sessions. Refer to the table above for what's supported when Workers aren't started in the same dev command.