adds new static routing options under run_worker_first

Author: korinne

src/content/docs/workers/static-assets/billing-and-limitations.mdx

@@ -11,9 +11,9 @@ description: Billing, troubleshooting, and limitations for Static assets on Work
 
 Requests to a project with static assets can either return static assets or invoke the Worker script, depending on if the request [matches a static asset or not](/workers/static-assets/routing/).
 
-Requests to static assets are free and unlimited. Requests to the Worker script (for example, in the case of SSR content) are billed according to Workers pricing. Refer to [pricing](/workers/platform/pricing/#example-2) for an example.
-
-There is no additional cost for storing Assets.
+- Requests to static assets are free and unlimited. Requests to the Worker script (for example, in the case of SSR content) are billed according to Workers pricing. Refer to [pricing](/workers/platform/pricing/#example-2) for an example.
+- There is no additional cost for storing Assets.
+- **Important note for free tier users**: When using [`run_worker_first`](/workers/static-assets/binding/#run_worker_first), requests matching the specified patterns will always invoke your Worker script. If you exceed your free tier request limits, these requests will receive a 429 (Too Many Requests) response instead of falling back to static asset serving.
 
 ## Limitations
 

src/content/docs/workers/static-assets/binding.mdx

@@ -63,6 +63,32 @@ Now Wrangler will not upload these files as client-side assets when deploying th
 
 Controls whether to invoke the Worker script regardless of a request which would have otherwise matched an asset. `run_worker_first = false` (default) will serve any static asset matching a request, while `run_worker_first = true` will unconditionally [invoke your Worker script](/workers/static-assets/routing/worker-script/#run-your-worker-script-first).
 
+You can also specify `run_worker_first` as an array of route patterns to selectively run the Worker first only for specific routes:
+
+<WranglerConfig>
+
+```toml title="wrangler.toml"
+name = "my-worker"
+compatibility_date = "2024-09-19"
+main = "src/index.ts"
+
+[assets]
+directory = "./public/"
+binding = "ASSETS"
+run_worker_first = [
+  "/api/**",        # API calls go to Worker first
+  "!/api/docs/**"   # EXCEPTION: For /api/docs/**, try static assets first
+]
+```
+
+</WranglerConfig>
+
+The array supports glob patterns with `**` for deep matching and exception patterns with `!` prefix. In this configuration, requests to `/api/**` routes will invoke the Worker script first, except for `/api/docs/**` which will follow the default asset-first routing behavior.
+
+<Aside type="caution">
+When using `run_worker_first`, requests matching the specified patterns will always invoke your Worker script. If you're on the free tier and exceed your request limits, these requests will receive a 429 (Too Many Requests) response instead of falling back to static asset serving. Consider this when designing your routing patterns.
+</Aside>
+
 <WranglerConfig>
 
 ```toml title="wrangler.toml"

src/content/docs/workers/static-assets/index.mdx

@@ -87,7 +87,7 @@ By default, if a requested URL matches a file in the static assets directory, th
 
 The default behavior for requests which don't match a static asset can be changed by setting the [`not_found_handling` option under `assets`](/workers/wrangler/configuration/#assets) in your Wrangler configuration file:
 
-- [`not_found_handling = "single-page-application"`](/workers/static-assets/routing/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.
+- [`not_found_handling = "single-page-application"`](/workers/static-assets/routing/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](/workers/static-assets/routing/single-page-application/#advanced-routing-control).
 - [`not_found_handling = "404-page"`](/workers/static-assets/routing/static-site-generation/#custom-404-pages): Sets your application to return a `404 Not Found` response with the nearest `404.html` for requests which don't match a static asset.
 
 <WranglerConfig>
@@ -101,8 +101,9 @@ The default behavior for requests which don't match a static asset can be change
 
 </WranglerConfig>
 
-If you want the Worker code to execute before serving an asset (for example, to protect an asset behind authentication), you can set `run_worker_first = true`.
+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-first routing:
 
+**Run Worker for all requests:**
 <WranglerConfig>
 
     ```toml
@@ -114,240 +115,45 @@ If you want the Worker code to execute before serving an asset (for example, to
 
 </WranglerConfig>
 
-<LinkCard
-	title="Routing options"
-	href="/workers/static-assets/routing/"
-	description="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](/cache/how-to/tiered-cache/) 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
-
-#### 1. Create a new Worker project
-
-```sh
-npm create cloudflare@latest -- my-dynamic-site
-```
-
-**For setup, select the following options**:
-
-- For _What would you like to start with?_, choose `Framework`.
-- For _Which framework would you like to use?_, choose `React`.
-- For _Which language do you want to use?_, choose `TypeScript`.
-- For _Do you want to use git for version control_?, choose `Yes`.
-- For _Do you want to deploy your application_?, choose `No` (we will be making some changes before deploying).
-
-After setting up the project, change the directory by running the following command:
-
-```sh
-cd my-dynamic-site
-```
-
-#### 2. Build project
-
-Run the following command to build the project:
-
-```sh
-npm run build
-```
-
-We should now see a new directory `/dist` in our project, which contains the compiled assets:
-
-<FileTree>
-- package.json
-- index.html
-- ...
-- dist Asset directory
-	- ... Compiled assets
-- src
-	- ...
-- ...
-
-</FileTree>
-
-In the next step, we use a Wrangler configuration file to allow Cloudflare to locate our compiled assets.
-
-#### 3. Add a Wrangler configuration file (`wrangler.toml` or `wrangler.json`)
-
-<WranglerConfig>
-
-    ```toml
-    	name = "my-spa"
-    	compatibility_date = "2025-01-01"
-    	[assets]
-    	directory = "./dist"
-    	```
-
-</WranglerConfig>
-
-**Notice the `[assets]` block**: here we have specified our directory where Cloudflare can find our compiled assets (`./dist`).
-
-Our project structure should now look like this:
-
-<FileTree>
-- package.json
-- index.html
-- **wrangler.toml** Wrangler configuration
-- ...
-- dist Asset directory
-	- ... Compiled assets
-- src
-	- ...
-- ...
-
-</FileTree>
-
-#### 4. Deploy with Wrangler
-
-```sh
-npx wrangler deploy
-```
-
-Our project is now deployed on Workers! But we can take this even further, by adding an **API Worker**.
-
-#### 5. Adjust our Wrangler configuration
-
-Replace the file contents of our Wrangler configuration with the following:
-
+**Run Worker first for specific routes only:**
 <WranglerConfig>
 
     ```toml
-    	name = "my-spa"
-    	main = "src/api/index.js"
-    	compatibility_date = "2025-01-01"
     	[assets]
     	directory = "./dist"
-    	binding = "ASSETS"
-    	not_found_handling = "single-page-application"
+    	run_worker_first = [
+    		"/api/**",          # API routes go to Worker first
+    		"/auth/**",         # Auth routes go to Worker first  
+    		"!/api/public/**"   # Exception: public API docs served as assets
+    	]
 
     	```
 
 </WranglerConfig>
 
-We have edited the Wrangler file in the following ways:
-
-- Added `main = "src/api/index.js"` to tell Cloudflare where to find our Worker code.
-- Added an `ASSETS` binding, which our Worker code can use to fetch and serve assets.
-- Enabled routing for Single Page Applications, which ensures that unmatched routes (such as `/dashboard`) serve our `index.html`.
-
-:::note
-
-By default, Cloudflare serves a `404 Not Found` to unmatched routes. To have the frontend handle routing instead of the server, you must enable `not_found_handling = "single-page-application"`.
+This selective approach allows you to protect specific routes behind authentication while serving other assets directly, and disables automatic `Sec-Fetch-Mode: navigate` detection for explicit routing control.
 
-:::
-
-#### 5. Create a new directory `/api`, and add an `index.js` file
-
-Copy the contents below into the index.js file.
-
-```js {13}
-// api/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);
-	},
-};
-```
-
-**Consider what this Worker does:**
-
-- Our Worker receives a HTTP request and extracts the URL.
-- If the request is for an API route (`/api/...`), it returns a JSON response.
-- Otherwise, it serves static assets from our directory (`env.ASSETS`).
-
-#### 6. Call the API from the client
-
-Edit `src/App.tsx` so that it includes an additional button that calls the API, and sets some state. Replace the file contents with the following code:
-
-```js {9,25, 33-47}
-
-// src/App.tsx
-import { useState } from "react";
-import reactLogo from "./assets/react.svg";
-import viteLogo from "/vite.svg";
-import "./App.css";
-
-function App() {
-  const [count, setCount] = useState(0);
-  const [name, setName] = useState("unknown");
-
-  return (
-    <>
-      <div>
-        <a href="https://vite.dev" target="_blank">
-          <img src={viteLogo} className="logo" alt="Vite logo" />
-        </a>
-        <a href="https://react.dev" target="_blank">
-          <img src={reactLogo} className="logo react" alt="React logo" />
-        </a>
-      </div>
-      <h1>Vite + React</h1>
-      <div className="card">
-        <button
-          onClick={() => setCount((count) => count + 1)}
-          aria-label="increment"
-        >
-          count is {count}
-        </button>
-        <p>
-          Edit <code>src/App.tsx</code> and save to test HMR
-        </p>
-      </div>
-      <div className="card">
-        <button
-          onClick={() => {
-            fetch("/api/")
-              .then((res) => res.json() as Promise<{ name: string }>)
-              .then((data) => setName(data.name));
-          }}
-          aria-label="get name"
-        >
-          Name from API is: {name}
-        </button>
-        <p>
-          Edit <code>api/index.ts</code> to change the name
-        </p>
-      </div>
-      <p className="read-the-docs">
-        Click on the Vite and React logos to learn more
-      </p>
-    </>
-  );
-}
-
-export default App;
-```
+<LinkCard
+	title="Routing options"
+	href="/workers/static-assets/routing/"
+	description="Learn more about how you can customize routing behavior."
+/>
 
-Before deploying again, we need to rebuild our project:
+### Caching behavior
 
-```sh
-npm run build
-```
+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.
 
-#### 7. Deploy with Wrangler
+- **First Request:** When an asset is requested for the first time, it is fetched from storage and cached at the nearest Cloudflare location.
 
-```sh
-npx wrangler deploy
+- **Subsequent Requests:** If a request for the same asset reaches a data center that does not have it cached, Cloudflare's [tiered caching system](/cache/how-to/tiered-cache/) 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
 
-Now we can see a new button **Name from API**, and if you click the button, we can see our API response as **Cloudflare**!
+<LinkCard
+	title="Vite + React SPA tutorial"
+	href="/workers/vite-plugin/tutorial/"
+	description="Learn how to build and deploy a full-stack Single Page Application with static assets and API routes."
+/>
 
 ## Learn more
 

src/content/docs/workers/static-assets/routing/single-page-application.mdx

@@ -33,6 +33,36 @@ Configuring `assets.not_found_handling` to `single-page-application` overrides t
 
 <Render file="navigation_requests" />
 
+## Advanced routing control
+
+For more explicit control over SPA routing behavior, you can use `run_worker_first` with an array of route patterns. This approach disables the automatic `Sec-Fetch-Mode: navigate` detection and gives you explicit control over which requests should be handled by your Worker script vs served as static assets.
+
+<WranglerConfig>
+
+```json
+{
+	"name": "my-spa-worker",
+	"compatibility_date": "$today",
+	"main": "./src/index.ts",
+	"assets": {
+		"directory": "./dist/",
+		"binding": "ASSETS",
+		"run_worker_first": [
+			"/app/**",        // App routes go to Worker for SPA handling
+			"!/app/assets/**" // Exception: static assets served directly
+		]
+	}
+}
+```
+
+</WranglerConfig>
+
+This configuration provides explicit routing control without relying on browser navigation headers, making it ideal for complex SPAs that need fine-grained routing behavior. Your Worker script will need to handle the matched routes and use the assets binding to serve the appropriate content.
+
+<Aside type="caution">
+When using `run_worker_first`, requests matching the specified patterns will always invoke your Worker script. If you're on the free tier and exceed your request limits, these requests will receive a 429 (Too Many Requests) response instead of falling back to static asset serving. Consider this when designing your routing patterns.
+</Aside>
+
 ## Local Development
 
 If you are using a Vite-powered SPA framework, you might be interested in using our [Vite plugin](/workers/vite-plugin/) which offers a Vite-native developer experience.