TL;DR: You can change what happens on a miss: - # Workers Static Assets The `assets.directory`

# 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: not_found_handling

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.

## When to use
You hit exactly this: Workers Static Assets: serve the SPA without invoking the Worker in Workers Static Assets.

## When not to use
A different error, or the same symptom in a different tool. This page only covers the failure above.

## Compatibility
Workers Static Assets.

## Edge cases
- with the nearest.
- The trap:.
- with API routes under the same Worker.
- for advanced control. ## The assets binding From Worker code you can defer back to static assets with the assets binding:.