Skip to content

Static Assets

Purpose

How every app's built React/Vite output is actually served - Cloudflare Worker Static Assets, not Cloudflare Pages.

The pattern (all 7 apps)

"assets": {
  "directory": "./dist",
  "not_found_handling": "single-page-application"
}
(Corporate/Software also add binding: "ASSETS" and run_worker_first - see Workers.) not_found_handling: "single-page-application" is the SPA fallback: any request that doesn't match a real file in dist/ serves index.html instead of a 404, so client-side routing (React Router or a hash-based router) works on a hard refresh/direct link to a deep route.

Build → deploy flow

npm run build:<app>     # produces apps/<app>/dist/
wrangler deploy --config apps/<app>/wrangler.jsonc    # uploads dist/ as the Worker's assets
CI runs exactly this sequence per app - see CI/CD → Deployment.

Why Worker Static Assets, not Cloudflare Pages

Every app in this repo needs a custom domain with custom_domain: true and (for 3 of them) a Worker that runs before falling back to assets - both are Workers-native concepts. Cloudflare Pages is a different, separate product; nothing in this repository configures a Pages project for the applications (only this documentation portal itself will use Pages - see Deployment).

Local development

npm run dev:<app> is a plain Vite dev server - it does not exercise the not_found_handling/run_worker_first behavior exactly as production does. For that, use npx wrangler dev from the app's own directory (see Workers "Local development").

Troubleshooting

  • A real client-side route 404s in production but works with npm run dev: check not_found_handling: "single-page-application" is still present in that app's wrangler.jsonc, and that no file under public//dist/ shares the exact path (a real file always wins over the SPA fallback).
  • A route inside a run_worker_first pattern (Corporate/Software/Admin) 404s: that's a Worker routing issue, not an asset issue - see Workers → Troubleshooting.
  • Deploy succeeds but the domain still serves old content: Cloudflare edge cache, or the deploy went to the wrong routes entry - see docs/DEPLOYMENT.md's own troubleshooting table and Troubleshooting.

Rollback

Redeploy a previous commit's build - see Operations → Rollback. There is no separate "static assets rollback" mechanism distinct from redeploying the Worker.