← Workers / workers

Static Assets

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=react

Or just deploy to Cloudflare

Learn more about supported frameworks on Workers.

When you deploy your project, Cloudflare deploys both your Worker code and your static assets in a single operation. This deployment operates as a tightly integrated "unit" running across Cloudflare's network, combining static file hosting, custom logic, and global caching.

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",
  // Set this to today's date
  "compatibility_date": "2026-08-28",
  "assets": {
    "directory": "./dist",
    "binding": "ASSETS"
  }
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-spa"
main = "src/index.js"
# Set this to today's date
compatibility_date = "2026-08-28"

[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 a 200 OK response with index.html for requests which don't match a static asset. Use this if you have a Single Page Application. We recommend pairing this with selective routing using run_worker_first for advanced routing control.
• not_found_handling = "404-page": Sets your application to return a 404 Not Found response with the nearest 404.html for 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-08-28",
	"main": "./src/index.ts",
	"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-08-28"
main = "./src/index.ts"

[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.

Cloudflare provides automatic caching for static assets across its network, ensuring fast delivery to users worldwide. When a static asset is requested, it is automatically cached for future requests.

• 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.