You can upload static assets (HTML, CSS, images and other files) as part of your Worker, and Cloudflare will handle caching and serving them to web browsers.
Start from CLI - Scaffold a React SPA with an API Worker, and use the Cloudflare Vite plugin.
npm create cloudflare@latest -- my-react-app --framework=reactyarn create cloudflare my-react-app --framework=reactpnpm create cloudflare@latest my-react-app --framework=reactOr just deploy to Cloudflare
Learn more about supported frameworks on Workers.
Supported frameworks
Your Worker code, configuration, and static assets belong to a Worker version. Each version has an asset manifest that maps request paths to uploaded files. Each request uses the selected version's files. This also applies when Cloudflare serves assets without running your Worker code.
Deploying sets which versions receive traffic. The change takes time to reach every location on Cloudflare's network. During this time, requests for HTML and its assets can use different versions. Uploading an asset does not add it to earlier versions' manifests. Refer to Version skew and static assets for ways to plan for these requests.
The assets directory specified in your Wrangler configuration file is central to this design. During deployment, Wrangler automatically uploads the files from this directory to Cloudflare's infrastructure. Once deployed, requests for these assets are routed efficiently to locations closest to your users.
{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "my-spa",
"main": "src/index.js",
"upload_source_maps": true,
// Set this to today's date
"compatibility_date": "2026-11-16",
"assets": {
"directory": "./dist",
"binding": "ASSETS"
}
}"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-spa"
main = "src/index.js"
upload_source_maps = true
# Set this to today's date
compatibility_date = "2026-11-16"
[assets]
directory = "./dist"
binding = "ASSETS"By adding an assets binding, you can directly fetch and serve assets within your Worker code.
// index.js
export default {
async fetch(request, env) {
const url = new URL(request.url);
if (url.pathname.startsWith("/api/")) {
return new Response(JSON.stringify({ name: "Cloudflare" }), {
headers: { "Content-Type": "application/json" },
});
}
return env.ASSETS.fetch(request);
},
};from workers import WorkerEntrypoint, Response
from urllib.parse import urlparse
class Default(WorkerEntrypoint):
async def fetch(self, request):
# Example of serving static assets
url = urlparse(request.url)
if url.path.startswith("/api/):
return Response.json({"name": "Cloudflare"})
return await self.env.ASSETS.fetch(request)By default, if a requested URL matches a file in the static assets directory, that file will be served — without invoking Worker code. If no matching asset is found and a Worker script is present, the request will be processed by the Worker. The Worker can return a response or choose to defer again to static assets by using the assets binding (e.g. env.ASSETS.fetch(request)). If no Worker script is present, a 404 Not Found response is returned.
The default behavior for requests which don't match a static asset can be changed by setting the not_found_handling option under assets in your Wrangler configuration file:
not_found_handling = "single-page-application": Sets your application to return a200 OKresponse withindex.htmlfor requests which don't match a static asset. Use this if you have a Single Page Application. We recommend pairing this with selective routing usingrun_worker_firstfor advanced routing control.not_found_handling = "404-page": Sets your application to return a404 Not Foundresponse with the nearest404.htmlfor requests which don't match a static asset.
{
"assets": {
"directory": "./dist",
"not_found_handling": "single-page-application"
}
}[assets]
directory = "./dist"
not_found_handling = "single-page-application"If you want the Worker code to execute before serving assets, you can use the run_worker_first option. This can be set to true to invoke the Worker script for all requests, or configured as an array of route patterns for selective Worker-script-first routing:
Invoking your Worker script on specific paths:
{
"name": "my-spa-worker",
// Set this to today's date
"compatibility_date": "2026-11-16",
"main": "./src/index.ts",
"upload_source_maps": true,
"assets": {
"directory": "./dist/",
"not_found_handling": "single-page-application",
"binding": "ASSETS",
"run_worker_first": ["/api/*", "!/api/docs/*"]
}
}name = "my-spa-worker"
# Set this to today's date
compatibility_date = "2026-11-16"
main = "./src/index.ts"
upload_source_maps = true
[assets]
directory = "./dist/"
not_found_handling = "single-page-application"
binding = "ASSETS"
run_worker_first = [ "/api/*", "!/api/docs/*" ]For a more advanced pattern, refer to SPA shell with bootstrap data, which uses HTMLRewriter to inject prefetched API data into the HTML stream.
Routing options
Cloudflare automatically caches static assets across its network. If the selected version's manifest includes the requested file, Cloudflare serves it from cache or fetches it from storage.
- First Request: When an asset is requested for the first time, it is fetched from storage and cached at the nearest Cloudflare location.
- Subsequent Requests: If a request for the same asset reaches a data center that does not have it cached, Cloudflare's tiered caching system allows it to be retrieved from a nearby cache rather than going back to storage. This improves cache hit ratio, reduces latency, and reduces unnecessary origin fetches.
Suppose version A includes /assets/app-a1b2.js, but version B does not. If a request for that file reaches B, Cloudflare treats it as a missing asset, even if it has a cached copy from A.