Pandemic Darlings The pandemic economy, in original documents
Home Source documents Static Assets — Cloudflare Workers docs

Static Assets — Cloudflare Workers docs

Summary

This Cloudflare Workers documentation page on static assets, last updated Oct 12, 2026, explains how HTML, CSS, images and other files can be uploaded as part of a Worker and served by Cloudflare. The Worker code and assets deploy together; Wrangler uploads the assets directory named in the configuration file, and an assets binding lets Worker code fetch the files. By default a request that matches a file is served without invoking the Worker; otherwise the Worker handles it, and a 404 Not Found is returned if no Worker script is present. The not_found_handling option can serve index.html for a single-page application or the nearest 404.html, and run_worker_first runs the Worker before assets for all or selected routes. Assets are cached automatically, and tiered caching lets a data center fetch an asset from a nearby cache.

Summary drafted by a model from the document's text below and checked by script against that text before publication. It is a navigation aid, not a reading of what the document proves. Where AI is used

Full text

Static Assets

Last updated Oct 12, 2026 | | View as Markdown | Agent setup

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.

Supported frameworks

Start building on Workers with our framework guides.

How it works

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",
  "upload_source_maps": true,
  // Set this to today's date
  "compatibility_date": "2026-10-18",
  "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-10-18"

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

Routing behavior

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-10-18",
	"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-10-18"
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

Learn more about how you can customize routing behavior.

Caching behavior

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.

Try it out

Vite + React SPA tutorial

Learn how to build and deploy a full-stack Single Page Application with static assets and API routes.

Learn more

Supported frameworks

Start building on Workers with our framework guides.

Billing and limitations

Learn more about how requests are billed, current limitations, and troubleshooting.

Was this helpful?

File and source

File
WB075.html
Size
219,234 bytes
SHA-256
5c04fc43c07079926e86b2f7b690b710956a26b06a463b30aca1d79b27136660
Our copy
WB075.html
Original
No public link identified.
Back to top