diff --git a/src/content/docs/workers/development-testing/multi-workers.mdx b/src/content/docs/workers/development-testing/multi-workers.mdx new file mode 100644 index 000000000000000..99ec0ceae200941 --- /dev/null +++ b/src/content/docs/workers/development-testing/multi-workers.mdx @@ -0,0 +1,99 @@ +--- +pcx_content_type: concept +title: Developing with multiple Workers +sidebar: + order: 3 +head: [] +description: Learn how to develop with multiple Workers using different approaches and configurations. +--- + +import { Aside, PackageManagers, Steps, WranglerConfig } from "~/components"; + +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** + + + +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: + +```js title="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: + + + +**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. + + + + + +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.