Workers Static Assets: serve the SPA without invoking the Worker

Workers Static Assets

The assets.directory in your Wrangler config (e.g. ./dist) is uploaded at deploy time. Requests matching a file in that directory are served from the edge without invoking your Worker. That is the cost story: asset hits are free of Worker invocations.

The miss behavior: notfoundhandling

When no asset matches and a Worker script exists, the request goes to the Worker. You can change what happens on a miss:

• single-page-application: return 200 OK with index.html. Use for SPAs.
• 404-page: return 404 with the nearest 404.html. Use for static sites.

The trap: single-page-application with API routes under the same Worker. A request to /api/records/1 that misses the assets directory falls through to the Worker, which is what you want, but only if your routing distinguishes API paths from SPA paths. The docs recommend pairing SPA handling with selective routing via run_worker_first for advanced control.

The assets binding

From Worker code you can defer back to static assets with the assets binding: env.ASSETS.fetch(request). Useful when the Worker decides a request should be served as a static file after all.

Checklist

• With the Cloudflare Vite plugin you do not set assets.directory yourself; the plugin handles it.
• API routes should live under a prefix (/api) that never collides with asset paths.
• Verify the built dist output locally before deploy: a missing index.html turns every SPA route into a confusing failure.

Verified against the live Static Assets doc: assets.directory upload, asset hits skip Worker invocation, notfoundhandling options, env.ASSETS.fetch, runworkerfirst pairing, Vite plugin exemption. Ref: https://developers.cloudflare.com/workers/static-assets/