Skip to content
Cloudflare Docs

Worker script

If you have both static assets and a Worker script configured, Cloudflare will first attempt to serve static assets if one matches the incoming request. You can read more about how we match assets in the HTML handling docs.

If an appropriate static asset if not found, Cloudflare will invoke your Worker script.

This allows you to easily combine together these two features to create powerful applications (e.g. a full-stack application, or a Single Page Application (SPA) or Static Site Generation (SSG) application with an API).

Run your Worker script first

You can configure the assets.run_worker_first setting to control when your Worker script runs relative to static asset serving. This gives you more control over exactly how and when those assets are served and could be considered a platform-level "middleware" feature.

Run Worker before each request

If you need to always run your Worker script before serving static assets (for example, you wish to log requests, perform some authentication checks, use HTMLRewriter, or otherwise transform assets before serving), set run_worker_first to true:

{
  "name": "my-worker",
  "compatibility_date": "2025-06-18",
  "main": "./worker/index.ts",
  "assets": {
    "directory": "./dist/",
    "binding": "ASSETS",
    "run_worker_first": true
  }
}

Run Worker first for selective paths

You can also configure selective Worker-first routing using an array of route patterns, often paired with the single-page-application setting. This allows you to run the Worker first only for specific routes while letting other requests follow the default asset-first behavior:

{
  "name": "my-worker",
  "compatibility_date": "2025-06-18",
  "main": "./worker/index.ts",
  "assets": {
    "directory": "./dist/",
    "not_found_handling": "single-page-application",
    "binding": "ASSETS",
    "run_worker_first": ["/api/*", "!/api/docs/*"]
  }
}