Skip to content

Commit 0fc5134

Browse files
edmundhungedmundhung
committed
update draft
1 parent fde2029 commit 0fc5134

File tree

1 file changed

+80
-100
lines changed

1 file changed

+80
-100
lines changed

‎src/content/docs/workers/development-testing/multi-workers.mdx‎

Lines changed: 80 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -1,138 +1,118 @@
11
---
22
pcx_content_type: concept
3-
title: Multi Workers development
3+
title: Developing with multiple Workers
44
sidebar:
55
order: 3
66
head: []
77
description: Learn how to develop with multiple Workers using different approaches and configurations.
88
---
99

10-
import { Aside, PackageManagers, Steps, WranglerConfig } from "~/components";
10+
import { PackageManagers, Steps, WranglerConfig } from "~/components";
1111

12-
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.
12+
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.
1313

14-
## Single dev session
14+
## Single dev command
1515

16-
You can run multiple Workers in a single dev session by passing multiple configuration files to your dev server.
16+
You can run multiple Workers in a single dev command by passing multiple configuration files to your dev server:
1717

18-
<Steps>
19-
20-
1. Create separate configuration files for each Worker:
21-
22-
**Primary Worker**
23-
24-
<WranglerConfig>
25-
```toml
26-
name = "app-worker"
27-
main = "./src/index.ts"
28-
29-
[[services]]
30-
binding = "API"
31-
service = "api-worker"
32-
```
33-
</WranglerConfig>
34-
35-
36-
**Auxiliary Worker**
37-
38-
<WranglerConfig>
39-
```toml
40-
name = "api-worker"
41-
main = "./src/index.ts"
42-
```
43-
</WranglerConfig>
44-
45-
2. Start a dev session:
46-
47-
**Using Wrangler**
18+
**Using Wrangler**
4819

49-
<PackageManagers
50-
type="exec"
51-
pkg="wrangler"
52-
args="dev -c wrangler.jsonc -c ../api/wrangler.jsonc"
53-
/>
54-
55-
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.
20+
<PackageManagers
21+
type="exec"
22+
pkg="wrangler"
23+
args="dev -c wrangler.app.jsonc -c wrangler.api.jsonc"
24+
/>
25+
26+
The first config (`wrangler.app.jsonc`) is treated as the primary Worker, exposed at `http://localhost:8787`. Additional configs (e.g. `wrangler.api.jsonc`) run as auxiliary Workers, available via service bindings or tail consumers from the primary Worker.
27+
28+
**Using the Vite plugin**
29+
30+
Configure `auxiliaryWorkers` in your Vite configuration:
31+
32+
```js title="vite.config.js"
33+
import { defineConfig } from "vite";
34+
import { cloudflare } from "@cloudflare/vite-plugin";
35+
36+
export default defineConfig({
37+
plugins: [
38+
cloudflare({
39+
configPath: "./wrangler.app.jsonc",
40+
auxiliaryWorkers: [
41+
{
42+
configPath: "./wrangler.api.jsonc",
43+
},
44+
],
45+
}),
46+
],
47+
});
48+
```
5649

57-
**Using the Vite plugin**
58-
59-
Configure `auxiliaryWorkers` in your Vite configuration:
60-
61-
```js title="vite.config.js"
62-
import { defineConfig } from "vite";
63-
import { cloudflare } from "@cloudflare/vite-plugin";
64-
65-
export default defineConfig({
66-
plugins: [
67-
cloudflare({
68-
configPath: "./wrangler.jsonc",
69-
auxiliaryWorkers: [
70-
{
71-
configPath: "../api/wrangler.jsonc",
72-
},
73-
],
74-
}),
75-
],
76-
});
77-
```
78-
79-
Then run:
80-
81-
<PackageManagers type="exec" pkg="vite" args="dev" />
50+
Then run:
8251

83-
</Steps>
52+
<PackageManagers type="exec" pkg="vite" args="dev" />
8453

85-
Use this approach when:
54+
**Use this approach when:**
8655

87-
- Workers are closely related or part of the same application
88-
- You want the simplest development setup
89-
- You need to access a Durable Object namespace from another Worker using `script_name`
56+
- Workers are part of the same application or codebase
57+
- You want the simplest setup without the full binding support
58+
- You need to access a Durable Object namespace from another Worker using `script_name`, or you are testing Queues where the producer and consumer Workers are seperated.
9059

91-
## Multiple dev sessions
60+
We recommend this approach as the default for most development workflows. Running multiple Workers in a single dev command ensures the best compatibility with features like service bindings, Durable Objects, and Queues.
9261

93-
You can also run each Worker in a separate dev session, each with its own terminal and configuration.
62+
## Multiple dev commands
9463

95-
```sh
96-
# Terminal 1
97-
cd app-worker
98-
wrangler dev
99-
```
64+
You can also run each Worker in a separate dev commands, each with its own terminal and configuration.
10065

101-
```sh
102-
# Terminal 2
103-
cd api-worker
104-
wrangler dev
105-
```
66+
<PackageManagers
67+
comment="Terminal 1"
68+
type="exec"
69+
pkg="wrangler"
70+
args="dev -c wrangler.app.jsonc"
71+
/>
10672

107-
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`**.
73+
<PackageManagers
74+
comment="Terminal 2"
75+
type="exec"
76+
pkg="wrangler"
77+
args="dev -c wrangler.api.jsonc"
78+
/>
10879

109-
Use this approach when:
80+
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`**.
11081

111-
- Each Worker uses a different build configuration
112-
- Different teams maintain the Workers
113-
- A Worker only occasionally accesses another, and you prefer the flexibility to run them separately
82+
**Limitations**
11483

115-
While this setup offers flexibility, there are some limitations to be aware of when using bindings across Workers running in separate dev sessions:
84+
While this setup offers flexibility, some bindings are not available when Workers are started in separate dev commands instead of being run together:
11685

117-
| Bindings | Wrangler (single config) | Wrangler (multi config) | Vite (no auxiliaryWorkers) | Vite (with auxiliaryWorkers) |
118-
|------------------|:-------------------------:|:----------------------------:|:--------------------------:|:----------------------------:|
119-
| Service Bindings | ✅ | 🔜 | ✅ | ✅ |
120-
| Durable Objects | ⚠️ | ❌ | ❌ | ❌ |
121-
| Tail Consumers | ✅ | 🔜 | ✅ | ✅ |
86+
| Bindings | Wrangler (single config) | Wrangler (multi config) | Vite |
87+
|------------------|:-------------------------:|:-----------------------:|:----:|
88+
| Service Bindings | ✅ | 🔜 | ✅ |
89+
| Durable Objects | ⚠️ | ❌ | ❌ |
90+
| Tail Consumers | ✅ | 🔜 | ✅ |
12291

12392
✅ = Full support.<br />
12493
⚠️ = Fetch only. RPC is not supported.<br />
12594
🔜 = No support yet. Coming soon.<br />
12695
❌ = Not supported.<br />
12796

97+
**Use this approach when:**
98+
99+
- Each Worker has its own build setup or tooling — for example, one uses Vite with custom plugins while another is a vanilla Wrangler project
100+
- You need the flexibility to run and develop Workers independently without restructuring your project or consolidating configs
101+
- Your Workers live in different repositories or are maintained by separate teams
102+
103+
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.
104+
128105
## Hybrid approach
129106

130107
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`.
131108

132-
This allows you to keep tightly coupled Workers in a single dev session, while treating independent or shared Workers as separate sessions. However, 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.
109+
This allows you to keep tightly coupled Workers running under a single dev command, while keeping independent or shared Workers in separate ones. However, the same limitations for bindings apply when Workers are run across multiple dev commands. Refer to the table above for what's supported when Workers aren't started in the same dev command.
110+
111+
**Use this approach when:**
112+
113+
- You want the convenience of developing related Workers together, while keeping others separate
114+
- You are working with a shared or legacy Worker that doesn't fit into your main dev setup
115+
- You are gradually migrating multiple Workers into a unified setup but need flexibility during transition
133116

134-
Use this approach when:
117+
Hybrid setups are useful when combining Workers maintained by different teams or projects. Rather than restructuring everything to run in a single dev command, you can run what makes sense together and leave others isolated.
135118

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

0 commit comments

Comments
 (0)