Skip to content

Commit b5539dc

Browse files
edmundhungedmundhung
committed
update draft
1 parent b48c9f3 commit b5539dc

File tree

1 file changed

+151
-76
lines changed

1 file changed

+151
-76
lines changed

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

Lines changed: 151 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,111 +1,186 @@
11
---
2-
pcx_content_type: navigation
2+
pcx_content_type: concept
33
title: Multi Workers development
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 } from "~/components";
10+
import { Aside, PackageManagers, Steps, WranglerConfig } from "~/components";
1111

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

14-
## Running in a single process
14+
## Single process
15+
16+
You can run multiple Workers in a single process by passing multiple configuration files to your dev server.
17+
18+
### Example setup
19+
20+
<Steps>
21+
22+
1. Create separate configuration files for each Worker:
23+
24+
**Primary Worker** (e.g. `wrangler.toml`)
25+
26+
<WranglerConfig>
27+
```toml
28+
name = "worker-a"
29+
main = "./src/index.ts"
30+
31+
[[services]]
32+
binding = "WORKER_B"
33+
service = "worker-b"
34+
```
35+
</WranglerConfig>
36+
37+
38+
**Auxiliary Worker** (e.g. `../other-worker/wrangler.jsonc`)
39+
40+
<WranglerConfig>
41+
```toml
42+
name = "worker-b"
43+
main = "./src/index.ts"
44+
```
45+
</WranglerConfig>
46+
47+
2. Start a dev session:
48+
49+
**Using Wrangler**
50+
51+
<PackageManagers
52+
type="exec"
53+
pkg="wrangler"
54+
args="dev -c wrangler.toml -c ../other-worker/wrangler.jsonc"
55+
/>
56+
57+
The first config is treated as the primary Worker, exposed at `http://localhost:8787`. Additional configs are run as auxiliary Workers, available via service bindings or tail consumers from the primary Worker.
58+
59+
**Using the Vite plugin**
60+
61+
Configure `auxiliaryWorkers` in your Vite configuration:
62+
63+
```js title="vite.config.js"
64+
import { defineConfig } from "vite";
65+
import { cloudflare } from "@cloudflare/vite-plugin";
66+
67+
export default defineConfig({
68+
plugins: [
69+
cloudflare({
70+
configPath: "./wrangler.toml",
71+
auxiliaryWorkers: [
72+
{
73+
configPath: "../other-worker/wrangler.jsonc",
74+
},
75+
],
76+
}),
77+
],
78+
});
79+
```
80+
81+
Then run:
82+
83+
<PackageManagers type="exec" pkg="vite" args="dev" />
84+
85+
</Steps>
86+
87+
### When to use
88+
89+
Use this approach when:
1590

16-
Run multiple Workers in a single process by passing multiple configuration files to `wrangler dev`. Each configuration should point to a different Worker:
91+
- Workers are closely related or part of the same application
92+
- You want the simplest development setup
93+
- You need to access a Durable Object namespace from another Worker using `script_name`
94+
95+
## Multiple processes
1796

18-
<PackageManagers
19-
type="exec"
20-
pkg="wrangler"
21-
args="dev -c wrangler.toml -c ../other-worker/wrangler.jsonc"
22-
/>
97+
You can also run each Worker in a separate dev session, each with its own terminal and configuration.
2398

24-
The first configuration will be treated as the **primary Worker**, exposed over HTTP at `http://localhost:8787`. Additional configurations become **secondary Workers**, accessible only via service bindings from the primary Worker.
99+
### Example setup
25100

26-
### Using Vite plugin
101+
<Steps>
27102

28-
If you are using the Vite plugin, configure `auxiliaryWorkers` in your Vite configuration:
103+
1. Open separate terminal windows for each Worker.
29104

30-
```js title="vite.config.js"
31-
import { defineConfig } from "vite";
32-
import { cloudflare } from "@cloudflare/vite-plugin";
105+
2. Run each dev session independently:
33106

34-
export default defineConfig({
35-
plugins: [
36-
cloudflare({
37-
configPath: "./wrangler.toml",
38-
auxiliaryWorkers: [
39-
{
40-
configPath: "../other-worker/wrangler.jsonc",
41-
},
42-
],
43-
}),
44-
],
45-
});
46-
```
107+
**Terminal 1 - First Worker**
108+
109+
<PackageManagers
110+
type="exec"
111+
pkg="wrangler"
112+
args="dev"
113+
/>
47114

48-
<Aside type="note">
49-
Auxiliary Workers are additional Workers used as part of your application. Use [service bindings](/workers/runtime-apis/bindings/service-bindings/) to call auxiliary Workers from your main Worker. All requests are routed through your primary Worker.
50-
</Aside>
115+
**Terminal 2 - Second Worker**
116+
117+
<PackageManagers
118+
type="exec"
119+
pkg="wrangler"
120+
args="dev"
121+
/>
51122

52-
## Running in multiple processes
123+
These sessions run in different processes, but can still communicate with each other if configured as service bindings or tail consumers.
53124

54-
Run separate development sessions for independent Workers. Each session runs in its own process with its own configuration:
125+
</Steps>
55126

56-
<PackageManagers
57-
type="exec"
58-
pkg="wrangler"
59-
args="dev"
60-
comment="Terminal 1 - First Worker"
61-
/>
127+
### When to use
62128

63-
<PackageManagers
64-
type="exec"
65-
pkg="vite"
66-
args="dev"
67-
comment="Terminal 2 - Second Worker"
68-
/>
129+
Use this approach when:
130+
131+
- Each Worker requires a different build configuration
132+
- Different teams maintain the Workers
133+
- A Worker only occasionally accesses another, and you prefer the flexibility to run them separately
69134

70-
Each development session runs independently, but you can still connect them using service bindings.
135+
### Limitations
136+
137+
The following features have different levels of support across approaches:
138+
139+
| Feature | Single process (Wrangler) | Multiple processes (Wrangler) | Single process (Vite) |
140+
|------------------|:-------------------------:|:----------------------------:|:--------------------:|
141+
| Service Bindings | ✅ Full support | ❌ Not supported | ✅ Full support |
142+
| Durable Objects | ⚠️ No RPC support | ❌ Not supported | ❌ Not supported |
143+
| Tail Consumers | ✅ Full support | ❌ Not supported | ✅ Full support |
144+
145+
We are actively working to address these limitations in future releases.
71146

72147
## Hybrid approach
73148

74-
Combine single and multiple process approaches. For example, run multiple Workers through Vite while connecting to a separate Worker running in its own `wrangler dev` session:
149+
You can mix the two approaches. For example, run a primary Worker and its auxiliary Workers through `vite dev`, while connecting to another Worker running separately in a `wrangler dev` session.
75150

76-
<PackageManagers
77-
type="exec"
78-
pkg="vite dev"
79-
comment="Terminal 1 - Vite with auxiliary Workers"
80-
/>
151+
### Example setup
81152

82-
<PackageManagers
83-
type="exec"
84-
pkg="wrangler dev"
85-
comment="Terminal 2 - Separate Worker"
86-
/>
153+
<Steps>
87154

88-
This approach provides flexibility when working with a mix of related and independent Workers.
155+
1. Set up Vite with auxiliary Workers as shown above.
89156

90-
## When to use each approach
157+
2. Run your development sessions in separate terminals:
91158

92-
### Single process
93-
Use when:
94-
- Workers are closely related or part of the same application
95-
- You need full support for service bindings, Durable Objects, and Tail consumers
96-
- You want the simplest development setup
159+
**Terminal 1 - Vite with auxiliary Workers**
160+
161+
<PackageManagers
162+
type="exec"
163+
pkg="vite"
164+
args="dev"
165+
/>
97166

98-
### Multiple processes
99-
Use when:
100-
- Workers are independent projects with different build setups
101-
- Different teams maintain the Workers
102-
- You need flexibility to run Workers together only when needed
167+
**Terminal 2 - Separate Worker**
168+
169+
<PackageManagers
170+
type="exec"
171+
pkg="wrangler"
172+
args="dev"
173+
/>
103174

104-
<Aside type="caution">
105-
The multiple processes approach has limitations:
106-
- Only `wrangler dev` sessions with a single configuration support cross-process Durable Objects namespaces
107-
- Cross-process communication is restricted to fetch requests only (no RPC calls)
108-
- `wrangler dev` with multiple configurations does not support hybrid mode bindings to Workers running in different processes
109-
</Aside>
175+
This approach provides flexibility when working with a mix of related and independent Workers.
176+
177+
</Steps>
178+
179+
### When to use
180+
181+
Use this approach when:
182+
183+
- You have an independent Worker that is shared across multiple applications
184+
- You are integrating with a legacy Worker that you don't want to refactor yet
185+
- Your project structure benefits from the flexibility of both approaches
110186

111-
We are actively working to address these limitations in future releases.

0 commit comments

Comments
 (0)