Skip to content
Cloudflare Docs

Developing with multiple Workers

When building complex applications, you may want 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 command

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

Using Wrangler

Terminal window
npx wrangler dev -c ./app/wrangler.jsonc -c ./api/wrangler.jsonc

The first config (./app/wrangler.jsonc) is treated as the primary Worker, exposed at http://localhost:8787. Additional configs (e.g. ./api/wrangler.jsonc) 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: "./app/wrangler.jsonc",
      auxiliaryWorkers: [
        {
          configPath: "./api/wrangler.jsonc",
        },
      ],
    }),
  ],
});

Then run:

Terminal window
npx vite dev

Use this approach when:

  • You want the simplest setup for development
  • Workers are part of the same application or codebase
  • You need to access a Durable Object namespace from another Worker using script_name, or setup Queues where the producer and consumer Workers are seperated.

Multiple dev commands

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

Terminal window
# Terminal 1
npx wrangler dev -c ./app/wrangler.jsonc
Terminal window
# Terminal 2
npx wrangler dev -c ./api/wrangler.jsonc

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

Use this approach when:

  • You want each Worker to be accessible on its own local URL during development, since only the primary Worker is exposed when using a single dev command
  • Each Worker has its own build setup or tooling — for example, one uses Vite with custom plugins while another is a vanilla Wrangler project
  • You need the flexibility to run and develop Workers independently without restructuring your project or consolidating configs

This setup is especially useful in larger projects where each team maintains a subset of Workers. Running everything in a single dev command might require significant restructuring or build integration that isn't always practical.