Skip to content
Cloudflare Docs

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.

Terminal window
npm create cloudflare@latest -- my-react-app --framework=react

Or just deploy to Cloudflare

Deploy to Workers

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.

{
  "name": "my-spa",
  "main": "src/index.js",
  "compatibility_date": "2025-01-01",
  "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);
  },
};

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:

{
  "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 run the Worker 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",
  "compatibility_date": "2025-06-18",
  "main": "./src/index.ts",
  "assets": {
    "directory": "./dist/",
    "not_found_handling": "single-page-application",
    "binding": "ASSETS",
    "run_worker_first": ["/app/*", "!/app/assets/*"]
  }
}
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.