Skip to content

Commit 55d0a61

Browse files
dinasaur404dinasaur404
authored
Improve WFP local development documentation (#23771)
1 parent fae7c6f commit 55d0a61

File tree

1 file changed

+9
-195
lines changed

1 file changed

+9
-195
lines changed

‎src/content/docs/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler.mdx‎

Lines changed: 9 additions & 195 deletions
Original file line numberDiff line numberDiff line change
@@ -7,217 +7,31 @@ sidebar:
77

88
import { Render, PackageManagers, WranglerConfig } from "~/components";
99

10-
To test your [Dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker), [user Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers) and [Outbound Worker](/cloudflare-for-platforms/workers-for-platforms/configuration/outbound-workers/) before deploying to production, you can use [Wrangler](/workers/wrangler) for development and testing.
10+
Test changes to your [dynamic dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker) by running the dynamic dispatch Worker locally but connecting it to User Workers deployed in production.
1111

12-
:::note
12+
This is helpful when:
13+
- **Testing routing changes** and validating that updates continue to work with deployed User Workers
14+
- **Adding new middleware** like authentication, rate limiting, or logging to the dynamic dispatch Worker
15+
- **Debugging issues** in the dynamic dispatcher that may be impacting deployed User Workers
1316

14-
Support for Workers for Platforms with `wrangler dev` in local mode is experimental and may change in the future. Use the prerelease branch: `wrangler@dispatch-namespaces-dev` to try Workers for Platforms locally.
15-
:::
17+
### How to use remote dispatch namespaces
1618

17-
## 1. Create a user worker
18-
19-
<PackageManagers
20-
type="create"
21-
pkg="cloudflare@latest"
22-
args={"customer-worker-1"}
23-
/>
24-
25-
<Render
26-
file="c3-post-run-steps"
27-
product="workers"
28-
params={{
29-
category: "hello-world",
30-
type: "Worker only",
31-
lang: "JavaScript",
32-
}}
33-
/>
34-
35-
Then, move into the newly created directory:
36-
37-
```sh
38-
cd customer-worker-1
39-
```
40-
41-
Update the `src/index.js` file for customer-worker-1:
42-
43-
```javascript
44-
export default {
45-
async fetch(request) {
46-
// make a subrequest to the internet
47-
const response = await fetch("https://example.com");
48-
return new Response(
49-
`user worker got "${await response.text()}" from fetch`,
50-
);
51-
},
52-
};
53-
```
54-
55-
Update the Wrangler file for customer-worker-1 and add the dispatch namespace:
56-
57-
<WranglerConfig>
58-
59-
```toml
60-
# ... other content above ...
61-
62-
dispatch_namespace = "my-namespace"
63-
```
64-
65-
</WranglerConfig>
66-
67-
## 2. Create a dispatch worker
68-
69-
<PackageManagers
70-
type="create"
71-
pkg="cloudflare@latest"
72-
args={"dispatch-worker"}
73-
/>
74-
75-
<Render
76-
file="c3-post-run-steps"
77-
product="workers"
78-
params={{
79-
category: "hello-world",
80-
type: "Worker only",
81-
lang: "JavaScript",
82-
}}
83-
/>
84-
85-
Then, move into the newly created directory:
86-
87-
```sh
88-
cd dispatch-worker
89-
```
90-
91-
Update the `src/index.js` file for dispatch-worker:
92-
93-
```javascript
94-
export default {
95-
async fetch(request, env) {
96-
// get the user Worker, specifying parameters that the Outbound Worker will see when it intercepts a user worker's subrequest
97-
const customerScript = env.DISPATCH_NAMESPACE.get(
98-
"customer-worker-1",
99-
{},
100-
{
101-
outbound: {
102-
paramCustomerName: "customer-1",
103-
},
104-
},
105-
);
106-
// invoke user Worker
107-
return await customerScript.fetch(request);
108-
},
109-
};
110-
```
111-
112-
Update the Wrangler file for dispatch-worker and add the dispatch namespace binding:
113-
114-
<WranglerConfig>
115-
116-
```toml
117-
# ... other content above ...
118-
119-
[[dispatch_namespaces]]
120-
binding = "DISPATCH_NAMESPACE"
121-
namespace = "my-namespace"
122-
outbound = { service = "outbound-worker", parameters = ["paramCustomerName"] }
123-
```
124-
125-
</WranglerConfig>
126-
127-
## 3. Create an Outbound Worker
128-
129-
<PackageManagers
130-
type="create"
131-
pkg="cloudflare@latest"
132-
args={"outbound-worker"}
133-
/>
134-
135-
<Render
136-
file="c3-post-run-steps"
137-
product="workers"
138-
params={{
139-
category: "hello-world",
140-
type: "Worker only",
141-
lang: "JavaScript",
142-
}}
143-
/>
144-
145-
Then, move into the newly created directory:
146-
147-
```sh
148-
cd outbound-worker
149-
```
150-
151-
Update the `src/index.js` file for outbound-worker:
152-
153-
```javascript
154-
export default {
155-
async fetch(request, env) {
156-
const { paramCustomerName } = env;
157-
// use the parameters passed by the dispatcher to know what this user this request is for
158-
// and return custom content back to the user worker
159-
return new Response(
160-
`intercepted a request for ${paramCustomerName} by the outbound`,
161-
);
162-
},
163-
};
164-
```
165-
166-
## 4. Start local dev session for your Workers
167-
168-
In separate terminals, start a local dev session for each of your Workers.
169-
170-
For your dispatcher Worker:
171-
172-
```sh
173-
cd dispatch-worker
174-
npx wrangler@dispatch-namespaces-dev dev --port 8600
175-
```
176-
177-
For your outbound Worker:
178-
179-
```sh
180-
cd outbound-worker
181-
npx wrangler@dispatch-namespaces-dev dev --port 8601
182-
```
183-
184-
And for your user Worker:
185-
186-
```sh
187-
cd customer-worker-1
188-
npx wrangler@dispatch-namespaces-dev dev --port 8602
189-
```
190-
191-
## 5. Test your requests
192-
193-
Send a request to your dispatcher Worker:
194-
195-
```sh
196-
curl http://localhost:8600
197-
```
198-
199-
```sh output
200-
# -> user worker got "intercepted a request for customer-1 by the outbound" from fetch
201-
```
202-
203-
## Remote dispatch namespaces
204-
205-
You can configure dispatch namespace bindings to connect to remote dispatch namespaces during local development by setting [`experimental_remote = true`](/workers/development-testing/#remote-bindings):
19+
In the dynamic dispatch Worker's Wrangler file, configure the [dispatch namespace binding](/workers/wrangler/configuration/#dispatch-namespace-bindings-workers-for-platforms) to connect to the remote namespace by setting [`experimental_remote = true`](/workers/development-testing/#remote-bindings):
20620

20721
<WranglerConfig>
20822
```jsonc title="wrangler.jsonc"
20923
{
21024
"dispatch_namespaces": [
21125
{
21226
"binding": "DISPATCH_NAMESPACE",
213-
"namespace": "testing",
27+
"namespace": "production",
21428
"experimental_remote": true
21529
}
21630
]
21731
}
21832
```
21933
</WranglerConfig>
22034

221-
This allows you to run your [dynamic dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker) locally, while connecting it to your remote dispatch namespace binding. You can then test changes to your core dispatching logic against real, deployed [user Workers](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers).
35+
This tells your dispatch Worker that's running locally to connect to the remote `production` namespace. When you run `wrangler dev`, your Dispatch Worker will route requests to the User Workers deployed in that namespace.
22236

22337
For more information about remote bindings during local development, refer to [remote bindings documentation](/workers/development-testing/#remote-bindings).

0 commit comments

Comments
 (0)