Improve Workers for Platforms documentation #27242
Conversation
dinasaur404
requested review from
a team,
GregBrimble,
MattieTK,
WalshyDev,
irvinebroque,
korinne,
mikenomitch and
securitypedant
as code owners
github-actions
bot
added
product:cloudflare-for-platforms
product:reference-architecture
product:workers
|
This PR requires additional review attention because it affects the following areas: RedirectsThis PR changes current filenames or deletes current files. Make sure you have redirects set up to cover the following paths:
|
github-actions
bot
assigned
securitypedant,
GregBrimble,
korinne,
MattieTK,
mikenomitch and
WalshyDev
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
|
CI run failed: build logs |
irvinebroque
left a comment
irvinebroque
left a comment
There was a problem hiding this comment.
How can we make getting started simple?
Ex: this content:
is:
- below the fold
- not on the getting started page
- not on the homepage of Cloudflare for Platforms
How can we get someone doing ^ that — and going whooaaaaaa it works
And then be like "okay how does it work though I want to understand" and read and invest the time to go deeper
If we do that — we invert it and get people moving and making progress.
| | `PUT https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/dispatch/namespaces/{namespace_name}/scripts/{script_name}/tags/{tag}` | Adds the single specified tag to the list of tags associated with the Worker script. | | ||
| | `DELETE https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/dispatch/namespaces/{namespace_name}/scripts/{script_name}/tags/{tag}` | Deletes the single specified tag from the list of tags associated with the Worker script. | | ||
| | `DELETE https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/dispatch/namespaces/{namespace_name}/scripts?tags={filter}` | Deletes all Worker scripts matching the filter. For example, `tags=testing:yes` would delete all scripts tagged with `testing`. | | ||
| | Method and endpoint | Description | |
There was a problem hiding this comment.
Something off with table
There was a problem hiding this comment.
@kodster28 good example here of the kind of thing that we might want to think about components in docs for?
Ex: here what we are trying to do is explain to someone in dev docs what REST APIs are available to do xyz — and link them to the right place
@dinasaur404 these need to link to our docs at https://developers.cloudflare.com/api/
There was a problem hiding this comment.
I think the simplest immediate action here would be to shorten the URl to the relevant part /accounts/{account_id} if she wanted to follow that format.
If up for a different format which -- for mobile + search + general usability -- header sections are way better than tables, should use APIRequest which makes the calls a lot more actionable + includes permissions directly to streamline the workflow.
| } from "~/components"; | ||
|
|
||
| ## Prerequisites: | ||
| ## Prerequisites |
There was a problem hiding this comment.
There is so much here in get started — versus having one clear place to get started.
How can we get this down to a single page?
There is a lot of content on the other pages that is both getting started and reference documentation
| ## Prerequisites: | ||
| ## Prerequisites | ||
|
|
||
| ### Enable Workers for Platforms |
There was a problem hiding this comment.
I think this can be clearer as a note component — clearly a prerequisite vs. part of the content
|
|
||
| If you are an Enterprise customer, contact your Cloudflare account team to enable Workers for Platforms. | ||
|
|
||
| ### Learn about Workers for Platforms |
There was a problem hiding this comment.
I wonder about taking diagram and reusing here — show the person visually who is getting started the thing they are about to deploy
| This guide walks you through setting up Workers for Platforms. You will configure a [dispatch namespace](/cloudflare-for-platforms/workers-for-platforms/how-workers-for-platforms-works/#dispatch-namespace), a [dynamic dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/how-workers-for-platforms-works/#dynamic-dispatch-worker), and a [user Worker](/cloudflare-for-platforms/workers-for-platforms/how-workers-for-platforms-works/#user-workers) to test a request end to end. | ||
|
|
||
| ### 1. Create a user Worker | ||
| ### 1. Create a dispatch namespace |
There was a problem hiding this comment.
How can we get the first thing someone does here with us to be Deploy to Cloudflare — see something real and working and feel successful — "I have done a thing and it works!"
and then go and do the mechanical steps to understand step by step how that thing works?
There was a problem hiding this comment.
Right now I think this is too reliant on the dashboard. People shouldn't need to go back and forth here so much.
There was a problem hiding this comment.
Basically — the steps outlined here are the ones that I would expect us to guide someone to take from within the WFP dashboard vs. explaining here in docs.
If I am in docs I want to click button have stuff work — then understand it
If I am reading instruction manual in one tab clicking buttons in dash in another...
|
|
||
| ### Dynamic dispatch Worker | ||
|
|
||
| A dynamic dispatch Worker is the entry point for all requests. You write this Worker to: |
There was a problem hiding this comment.
| A dynamic dispatch Worker is the entry point for all requests. You write this Worker to: | |
| A dynamic dispatch Worker is the entry point for all requests to your platform. Your dynamic dispatch Worker: |
|
|
||
| A dynamic dispatch Worker is the entry point for all requests. You write this Worker to: | ||
|
|
||
| - **Route requests** - Determine which customer Worker should handle each request based on hostname, path, headers, or any other criteria |
There was a problem hiding this comment.
| - **Route requests** - Determine which customer Worker should handle each request based on hostname, path, headers, or any other criteria | |
| - **Routes requests** - Determine which customer Worker should handle each request based on hostname, path, headers, or any other criteria |
|
|
||
| ### User Workers | ||
|
|
||
| User Workers contain code written by your customers. They are deployed to a dispatch namespace and invoked by your dynamic dispatch Worker. You can provide user Workers with [bindings](/cloudflare-for-platforms/workers-for-platforms/configuration/bindings/) to access KV, D1, R2, and other resources. |
There was a problem hiding this comment.
| User Workers contain code written by your customers. They are deployed to a dispatch namespace and invoked by your dynamic dispatch Worker. You can provide user Workers with [bindings](/cloudflare-for-platforms/workers-for-platforms/configuration/bindings/) to access KV, D1, R2, and other resources. | |
| User Workers contain code written by your customers. Your customer sends their code to your platform, and then you make an API request to deploy a user Worker on their behalf. They are deployed to a dispatch namespace and invoked by your dynamic dispatch Worker. You can provide user Workers with [bindings](/cloudflare-for-platforms/workers-for-platforms/configuration/bindings/) to access KV, D1, R2, and other resources. |
I am finding myself wanting to add this kind of sentence in many places to get super super clear that it goes:
- customer sends code to platform
- platform takes code, sends it to cloudflare as user Worker
Both — because this is the flow that there isn't a diagram of here (AFAIK) — and because of examples where this isn't followed or understood
|
|
||
| ### Outbound Worker (optional) | ||
|
|
||
| An [outbound Worker](/cloudflare-for-platforms/workers-for-platforms/configuration/outbound-workers/) intercepts `fetch()` requests made by user Workers. Use it to: |
There was a problem hiding this comment.
| An [outbound Worker](/cloudflare-for-platforms/workers-for-platforms/configuration/outbound-workers/) intercepts `fetch()` requests made by user Workers. Use it to: | |
| An [outbound Worker](/cloudflare-for-platforms/workers-for-platforms/configuration/outbound-workers/) intercepts [`fetch()`](/workers/runtime-apis/fetch/) requests made by user Workers. Use it to: |
|
|
||
| Both Workers for Platforms and [Service bindings](/workers/runtime-apis/bindings/service-bindings/) enable Worker-to-Worker communication. Use Service bindings when you know exactly which Workers need to communicate. Use Workers for Platforms when user Workers are uploaded dynamically by your customers. | ||
|
|
||
| You can use both simultaneously - your dynamic dispatch Worker can use Service bindings to call internal services while also dispatching to user Workers in a namespace. |
There was a problem hiding this comment.
non-blocking but — example?
9 participants
Summary
Major restructure and content improvements for Workers for Platforms documentation.
Content changes
Structure changes
how-workers-for-platforms-works.mdxfromreference/to top level (appears after overview)bindings.mdxfromget-started/toconfiguration/limits.mdx,pricing.mdx,worker-isolation.mdxfromplatform/toreference/platform/folderdemos.mdx(replaced by platform-examples)user-workers.mdx(covered in configuration and platform-examples)Link updates