Skip to content

Commit 15abe87

Browse files
edmundhungedmundhung
committed
update draft
1 parent fde2029 commit 15abe87

File tree

1 file changed

+70
-93
lines changed

1 file changed

+70
-93
lines changed

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

Lines changed: 70 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
pcx_content_type: concept
3-
title: Multi Workers development
3+
title: Developing with multiple Workers
44
sidebar:
55
order: 3
66
head: []
@@ -9,110 +9,85 @@ description: Learn how to develop with multiple Workers using different approach
99

1010
import { Aside, 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.
17-
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**
16+
<Aside type="note" title="When to use this approach?">
17+
- Workers are closely related or part of the same application
18+
- You want the simplest development setup
19+
- You need to access a Durable Object namespace from another Worker using `script_name`
20+
</Aside>
3721

38-
<WranglerConfig>
39-
```toml
40-
name = "api-worker"
41-
main = "./src/index.ts"
42-
```
43-
</WranglerConfig>
4422

45-
2. Start a dev session:
23+
You can run multiple Workers in a single dev command by passing multiple configuration files to your dev server:
4624

47-
**Using Wrangler**
25+
**Using Wrangler**
4826

49-
<PackageManagers
50-
type="exec"
51-
pkg="wrangler"
52-
args="dev -c wrangler.jsonc -c ../api/wrangler.jsonc"
53-
/>
27+
<PackageManagers
28+
type="exec"
29+
pkg="wrangler"
30+
args="dev -c wrangler.app.jsonc -c wrangler.api.jsonc"
31+
/>
32+
33+
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.
34+
35+
**Using the Vite plugin**
36+
37+
Configure `auxiliaryWorkers` in your Vite configuration:
38+
39+
```js title="vite.config.js"
40+
import { defineConfig } from "vite";
41+
import { cloudflare } from "@cloudflare/vite-plugin";
42+
43+
export default defineConfig({
44+
plugins: [
45+
cloudflare({
46+
configPath: "./wrangler.app.jsonc",
47+
auxiliaryWorkers: [
48+
{
49+
configPath: "./wrangler.api.jsonc",
50+
},
51+
],
52+
}),
53+
],
54+
});
55+
```
5456

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.
57+
Then run:
5658

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" />
59+
<PackageManagers type="exec" pkg="vite" args="dev" />
8260

83-
</Steps>
61+
## Multiple dev commands
8462

85-
Use this approach when:
8663

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`
90-
91-
## Multiple dev sessions
92-
93-
You can also run each Worker in a separate dev session, each with its own terminal and configuration.
64+
<Aside type="note" title="When to use this approach?">
65+
- Each Worker uses a different build configuration
66+
- Different teams maintain the Workers
67+
- A Worker only occasionally accesses another, and you prefer the flexibility of running them separately
68+
</Aside>
9469

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

101-
```sh
102-
# Terminal 2
103-
cd api-worker
104-
wrangler dev
105-
```
72+
<PackageManagers
73+
comment="Terminal 1"
74+
type="exec"
75+
pkg="wrangler"
76+
args="dev -c wrangler.app.jsonc"
77+
/>
10678

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`**.
79+
<PackageManagers
80+
comment="Terminal 2"
81+
type="exec"
82+
pkg="wrangler"
83+
args="dev -c wrangler.api.jsonc"
84+
/>
10885

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

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
88+
### Limitations
11489

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

11792
| Bindings | Wrangler (single config) | Wrangler (multi config) | Vite (no auxiliaryWorkers) | Vite (with auxiliaryWorkers) |
11893
|------------------|:-------------------------:|:----------------------------:|:--------------------------:|:----------------------------:|
@@ -127,12 +102,14 @@ While this setup offers flexibility, there are some limitations to be aware of w
127102

128103
## Hybrid approach
129104

105+
<Aside type="note" title="When to use this approach?">
106+
- You have an independent Worker that is shared across multiple applications
107+
- You are integrating with a legacy Worker that you don't want to refactor yet
108+
- Your project structure benefits from the flexibility of both approaches
109+
</Aside>
110+
130111
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`.
131112

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.
113+
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](#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.
133114

134-
Use this approach when:
135115

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)