Add SPA shell with bootstrap data example#28434
Conversation
Co-authored-by: irvinebroque <irvinebroque@users.noreply.github.com>
ask-bonk
bot
requested review from
a team,
GregBrimble,
MattieTK,
WalshyDev,
irvinebroque,
korinne and
mikenomitch
as code owners
github-actions
bot
assigned
GregBrimble,
irvinebroque,
korinne,
MattieTK,
mikenomitch and
WalshyDev
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
irvinebroque
left a comment
irvinebroque
left a comment
There was a problem hiding this comment.
/bonk please revise - this example needs to ALSO show how you can do this even when the HTML, CSS, and JS are all deployed outside of Cloudflare
|
/bonk please revise - this example needs to ALSO show how you can do this even when the HTML, CSS, and JS are all deployed outside of Cloudflare |
|
Done. Here is a summary of the changes made to address the review feedback: What changed in The page now presents two parallel variants instead of assuming the SPA is always on Workers Static Assets:
The shared sections (client-side consumption, additional injection techniques) remain unchanged since they apply to both variants. The "When to use this pattern" section now has guidance on choosing between the two options. Related resources now link to Custom Domains and Routes docs.
|
| - TypeScript | ||
| - SPA | ||
| pcx_content_type: example | ||
| title: SPA shell with bootstrap data |
There was a problem hiding this comment.
| title: SPA shell with bootstrap data | |
| title: Single Page App (SPA) shell with bootstrap data |
|
|
||
| Two variants are shown: | ||
|
|
||
| 1. **Static Assets** — The SPA is deployed to [Workers Static Assets](/workers/static-assets/) alongside the Worker. |
There was a problem hiding this comment.
| 1. **Static Assets** — The SPA is deployed to [Workers Static Assets](/workers/static-assets/) alongside the Worker. | |
| 1. **Static Assets** — The SPA is deployed using [Workers Static Assets](/workers/static-assets/) |
| Two variants are shown: | ||
|
|
||
| 1. **Static Assets** — The SPA is deployed to [Workers Static Assets](/workers/static-assets/) alongside the Worker. | ||
| 2. **External origin** — The SPA is hosted outside Cloudflare (for example, on AWS S3, Vercel, Netlify, or your own server) and the Worker sits in front of it as a reverse proxy. |
There was a problem hiding this comment.
| 2. **External origin** — The SPA is hosted outside Cloudflare (for example, on AWS S3, Vercel, Netlify, or your own server) and the Worker sits in front of it as a reverse proxy. | |
| 2. **External origin** — The SPA is hosted outside Cloudflare, and the Worker sits in front of it as a reverse proxy, improving performance |
|
|
||
| --- | ||
|
|
||
| ## Option 1: SPA on Workers Static Assets |
There was a problem hiding this comment.
| ## Option 1: SPA on Workers Static Assets | |
| ## Option 1: Single Page App (SPA) built entirely on Workers |
|
|
||
| ## Option 1: SPA on Workers Static Assets | ||
|
|
||
| Use this variant when your SPA build output is deployed alongside the Worker using [Workers Static Assets](/workers/static-assets/). |
There was a problem hiding this comment.
| Use this variant when your SPA build output is deployed alongside the Worker using [Workers Static Assets](/workers/static-assets/). | |
| Use this variant when your SPA build output is deployed as part of your Worker using [Static Assets](/workers/static-assets/). |
|
|
||
| Both variants use the same HTMLRewriter injection technique and the same client-side consumption pattern. Choose the one that matches your deployment. | ||
|
|
||
| This pattern works with any SPA framework — React, Vue, Svelte, or others. |
There was a problem hiding this comment.
Include links to the framework docs that are here:
https://developers.cloudflare.com/workers/framework-guides/web-apps
|
|
||
| ## Option 2: SPA hosted on an external origin | ||
|
|
||
| Use this variant when your HTML, CSS, and JavaScript are deployed outside Cloudflare — for example, on AWS S3, Google Cloud Storage, Vercel, Netlify, or your own server. The Worker acts as a reverse proxy: it fetches the SPA shell from the external origin, uses HTMLRewriter to inject bootstrap data, and streams the modified response to the browser. |
There was a problem hiding this comment.
| Use this variant when your HTML, CSS, and JavaScript are deployed outside Cloudflare — for example, on AWS S3, Google Cloud Storage, Vercel, Netlify, or your own server. The Worker acts as a reverse proxy: it fetches the SPA shell from the external origin, uses HTMLRewriter to inject bootstrap data, and streams the modified response to the browser. | |
| Use this variant when your HTML, CSS, and JavaScript are deployed outside Cloudflare. The Worker fetches the SPA shell from the external origin, uses HTMLRewriter to inject bootstrap data, and streams the modified response to the browser. |
| .transform(shell); | ||
| ``` | ||
|
|
||
| ## When to use this pattern |
|
/bonk update these docs based on my review, and based on the Workers best practices: https://developers.cloudflare.com/workers/best-practices/workers-best-practices/ |
…rkers best practices
|
Committed as |
|
/bonk please update this pull request based on the guidance below. There are additional pages in the developer docs that should reference what we are adding here, and need the additional content below. Please think hard about how to avoid adding extra complexity to existing documentation. While we want the docs to be clear and comprehensive, we do not want them to be littered with callouts and warnings and distractions. Need to strike a good balance.
|
Link to the new SPA shell with bootstrap data example from the five pages where readers are most likely to benefit from discovering it: SPA routing, Static Assets binding, HTMLRewriter API reference, Static Assets overview, and security headers example.
|
Done. Here's a summary of the 5 cross-link additions:
Each addition is one sentence plus a link — no callout boxes, no warnings, no code duplication. |
7 participants
All done. Here is a summary of what was created:
New file:
src/content/docs/workers/examples/spa-shell.mdxThis adds a new Workers example page at
/workers/examples/spa-shell/documenting the SPA Shell Pattern. The page covers:WranglerConfigblock showingnot_found_handling: "single-page-application",run_worker_first, and theASSETSbindingTypeScriptExamplewith the full Worker implementation: parallel data fetch, HTMLRewriter streaming the<head>immediately while awaiting API data for<body>injection, graceful fallback on API failurewindow.__BOOTSTRAP_DATA__, plus TypeScript global type declarationThe page uses
TypeScriptExampleandWranglerConfigcomponents (following theanalytics-engine.mdxpattern), tagsTypeScriptandSPA, and passesnpm run checkwith 0 errors.Closes #28433
github run