Proposal: Support for _routes.json in Workers with static assets

[korinne]

Hi 👋

I’m a product manager on the Workers team, and we’d like feedback on the following proposal for adding support for _routes.json configuration files when using Workers with static assets. In a _routes.json file, you can more granularly specify which routes invoke your Worker by specifying include and exclude rules. Many Cloudflare Pages projects use _routes.json in this way today, and our goal is to make it even easier to migrate from Pages to Workers, as well as solve some of the issues we’ve been receiving regarding our current routing.

Below I’ve included some background information on how routing currently works so that we can all get on the same page – you can skip to the actual proposal if you’re already familiar. It’s a bit long, but we’ve had enough questions about our routing that it felt necessary to outline.

Background - How routing currently works

Currently, you can upload and immediately route traffic to a fullstack app on Cloudflare Workers by configuring an assets block in your Wrangler configuration file and deploying:

{
 "name": "my-app",
 "main": "src/index.ts",
 "compatibility_date": "2025-01-01",
 "assets": {
   "directory": "./dist", // not necessary when using Cloudflare Vite plugin
   "binding": "ASSETS"
 }
}

This assets block informs Cloudflare that you have client-side code/an asset that can be found in your build output directory, which the platform then uploads. Then, when requests come in, Cloudflare looks at the request path and checks if there’s a file name in your assets directory that matches – if so, that asset is served directly. Put more simply, static assets have precedence by default. If there’s no match, your Worker code (if there is any) is invoked. If there is no Worker, we return an empty 404 response by default.

The original philosophy of this design was to treat your Worker as the primary entity, while still providing enough sensible defaults out-of-the-box. Assets can be served automatically by just matching the path to a file name, or you can treat static assets as a resource that the Worker can interact with (via the asset binding, env.ASSETS). Then, all your routing logic (especially for dynamic requests) can reside within your Worker code, providing you a lot more control over routing behavior. This allows you to decide if and when to involve the Worker in serving assets – you can use the path matching defaults, or change the behavior in your Wrangler config.

You have a few levers to change these defaults, but for the purpose of this proposal, we will focus on two:

• run_worker_first : Switches the routing behavior so that your Worker executes first for every request. This blunt instrument was intended for use-cases like gating assets behind authentication.
• “not_found_handling” = “single-page-application” : serves index.html for unmatched assets. You can also set not_found_handling to 404-page, in order to serve a custom 404-page for unmatched requests.

Problems

single-page-application mode

When we first released support for static assets in Workers, enabling single-page-application mode meant that if you had a server-side API alongside your SPA, all non-asset requests would get forwarded to your Worker’s fetch() handler before serving index.html . If a non-asset request was intended to go to index.html, it would need to be configured via the env.ASSETS binding. This meant that serving index.html for unmatched routes would always invoke your Worker, using up a request against your Worker’s request limit (and potentially incurring a financial cost).

This behavior got a lot of complaints, such as this issue. To fix this, we recently implemented a new default (assets_navigation_prefers_asset_serving), which infers whether a request that doesn’t match an asset should be served index.html , or should be handled by the Worker. The heuristic relies on the presence of a Sec-Fetch-Mode: navigate header, that is attached to browser navigation requests in modern browsers. If this header is present, we now invoke the not_found_handling behavior directly (for single-page-application mode, this means serving index.html).

This change, however, caused even more problems. Primarily:

• Users want to be able to view their API routes in the browser, including when not_found_handling equals single_page_application . With this new default behavior, however, navigating to your API in a browser means your request now has this special header attached, and you’ll see index.html instead of hitting API.

• Users want to send some browser navigations to their Worker, such as for OAuth redirects. With this new behavior, we broke a lot of OAuth flows unexpectedly.

We honestly moved too fast and broke things – we changed the defaults within a short time frame, didn’t have the proper docs up, and didn’t communicate these changes to the community. Now, we’d like to fix these problems with your feedback, and prevent these kinds of mishaps in the future.

run_worker_first

As mentioned, run_worker_first is a blunt instrument: routing either prefers assets by default, or prefers the Worker when run_worker_first is set to true. But there’s no declarative way currently to say “just invoke my Worker on these routes, else serve the assets.” It’s all or nothing.

Routing behavior is confusing

In general, we’ve consistently heard (and experienced ourselves in writing these kinds of documents) that our routing is “too magical” and a lot to keep in mind. The complex interplay between run_worker_first, direct path matching, the choice to call env.ASSETS.fetch() inside the Worker, and not_found_handling (along with our other configuration options) creates a system that is difficult to reason about. It’s difficult to pinpoint why a request was served directly, why the Worker ran, or why env.ASSETS.fetch() returned a specific result without deeply understanding all interacting configurations. While our intention was to give users more control over how requests are routed via the Worker, we ultimately failed in making this actually easy to use and understand.

Proposed solution

Our proposed solution is to support _routes.json configuration (as is present in Pages today) and run the _routes.json logic as an initial filter.

Depending on the request matching exclude or include patterns in _routes.json, this logic will delegate handling of the request to either:

• Our Asset service, responsible for serving assets.
• The Worker script that the user has written (we’ll call this the User Worker).
• Or our Routing service, which looks at how not_found_handling has been configured (either single_page_application or 404-page ) and serves either index.html or a custom 404-page.

The following diagram shows how requests might be handled depending on the not_found_handling configuration:

The routing algorithm is as follows:

1. Test the request against exclude routing patterns. If any match, then run Asset service handling.
2. Test the request against include routing patterns. If any match then run User Worker handling.
3. Otherwise, run the default Routing service handling.

The handling options are:

• User Worker: The request will skip the Routing service and go straight to the User Worker. The User Worker could then delegate back to the Asset service if desired by calling env.ASSETS.fetch(req).

• Asset service: The request will skip the Routing service and go straight to the Asset service. The Asset service will still apply its html_handling configuration as normal.

• Routing service: The request will go to the Routing service and follow its normal behaviour. This might involve forwarding the request to either the User Worker or Asset service depending upon the not_found_handling and the assets_navigation_prefers_asset_serving compatibility flag.

This approach has the following notable features:

• If there is no _routes.json, or it is empty, then there is no change to the current behaviour of Workers with static assets.

• A _routes.json that contains just { “include”: “*” } will be equivalent to ”run_worker_first”: true, making it superfluous. If this proposal is approved, we’d like to then deprecate run_worker_first to keep configuration options more sensible.

• The routing logic is close enough to Pages that it is trivial to migrate a Pages project that has a _routes.json file to Workers with assets.

Proposed solution examples

The scenarios below are based on the presence of a User Worker and the following assets:

• index.html
• 404.html
• code.js
• image.jpg
• assets/style.css

With the following _routes.json file:

{
  "version": 1,
  "include": ["/image.jpg", "/worker/*"],
  "exclude": ["/worker/b", "/assets/*"]
}

Navigation request (Sec-Fetch-Mode: navigate)

Request	not_found_handling
	none	404-page	single-page-application
/code.js	Returns /code.js	Returns /code.js	Returns /code.js
/missing	Invokes User Worker	Returns 404.html	Returns index.html
/image.jpg	Invokes User Worker	Invokes User Worker	Invokes User Worker
/worker/a	Invokes User Worker	Invokes User Worker	Invokes User Worker
/worker/b	Returns 404 response	Returns 404.html	Returns index.html
/assets/style.css	Returns assets/style.css	Returns assets/style.css	Returns assets/style.css
/assets/missing	Returns 404 response	Returns 404.html	Returns index.html

Non-navigation request

(blue is used to indicate where the behaviour differs from a navigation request)

Request	not_found_handling
	none	404-page	single-page-application
/code.js	Returns /code.js	Returns /code.js	Returns /code.js
/missing	Invokes User Worker	Invokes User Worker	Invokes User Worker
/image.jpg	Invokes User Worker	Invokes User Worker	Invokes User Worker
/worker/a	Invokes User Worker	Invokes User Worker	Invokes User Worker
/worker/b	Returns 404 response	Returns 404.html	Returns index.html
/assets/style.css	Returns assets/style.css	Returns assets/style.css	Returns assets/style.css
/assets/missing	Returns 404 response	Returns 404.html	Returns index.html

Other options considered

Given the proposed algorithm above, there were two other approaches that were considered. Each has slightly different corner-cases, ease of documenting and levels of surprise. The following table shows how the include and exclude settings of _routes.json would behave.

Option	Pattern match handling			Notes
	exclude	include	none
include matches go to User Worker, exclude matches go to Asset service, default handling (Routing service) otherwise	Asset service	User Worker	Routing service	This is the proposed approach. The _routes.json file can be used to fully control where requests are handled, but also allows the current default handling to kick in naturally. In this case the use of a _routes.json file is a purely additive feature, which means that it can be added by an application developer without affecting how a full-stack framework might handle routing.
Default handling except include matches go to User Worker	Routing service	User Worker	Routing service	This is the simplest implementation and deviates least from how Workers with assets works right now. This provides the least compatibility with Pages projects since it is possible for a request to be excluded but still end up at the User Worker. For example, if there is an excluded route that does not match an asset. In this case it will go to the User Worker if not_found_handling is none or if it is not a navigation request.
Only include matches go to User Worker, no default handling	Asset service	User Worker	Asset service	This effectively turns off Sec-Fetch-Mode behaviour and replaces the Routing service logic, when there is a _routes.json. Adding a _routes.json (even if it is empty) will change how routing of a request works. This arguably provides the most accurate compatibility with Pages projects but is not as intuitive when not_found_handling is set to none.

Call to action

• Please provide feedback on the above proposal. We’d love to hear if you think supporting _routes.json would improve the current routing behavior, or if the routing layers would get even more complicated. We’d love to hear any suggestions or feedback, even on the other options we’ve considered.

• Framework authors and maintainers – we’d love your feedback as well. You see first-hand many pain-points our users run into, and your insight is invaluable.

  • Note: this proposal would mean that _routes.json becomes a user-facing configuration file, and frameworks should avoid using it for framework-specific purposes. When combined with the built-in asset handling fallback, frameworks will no longer need to list entire asset manifests into the exclude rules in routes.json.

• If you have other general feedback about Workers with static assets, please feel free to join our community Discord, or you can book time with me directly to talk about your feedback on my calendar.

Thank you for reading through this longer post – we really appreciate it. And a huge thank you to @jamesopstad for driving this proposed solution, and putting tons of care into the routing scenarios.

Excited to get your thoughts, and thank you for using Workers and being such an engaged community.

[isaac-mcfadyen]

Very much excited for this proposal, _routes.json was one of the best parts of Pages.

One thing of note:

Note: this proposal would mean that _routes.json becomes a user-facing configuration file, and frameworks should avoid using it for framework-specific purposes

While I get exposing _routes.json to power users, part of the draw of _routes.json on Pages was that frameworks could do whatever they needed with it. They could exclude/include certain pages, or mark API routes as always firing the Worker/Function, etc.

I think that this should continue to happen. For example, if a framework has an OAuth plugin installed, it makes sense to have the framework add it to the include in _routes.json rather than the user manually adding it. Especially for users that aren't experienced with _routes.json, having the framework manage it for them (maybe with an override for power users so that they can still define custom routes) should still be a thing that can happen.

[korinne]

This is super valid -- @petebacondarwin something we should discuss. Thanks @isaac-mcfadyen for the feedback, we really appreciate it!

[petebacondarwin]

I was the one who added that sentence to this proposal. I'll try to explain the context and intent a bit...

In Pages, if there was no routes.json but there was Worker code (User Worker here) then all requests went to the User Worker. There was no way to direct some requests just to assets and avoid the User Worker. This is where _routes.json was essential, and for things like Pages Functions it worked well.

In Pages Functions we knew exactly which subpath requests should go to the User Worker, so we were able to just list those in the include rules of _routes.json.
But a number of frameworks were either not able to determine these positive include rules, or chose not to; instead they flipped the routing and just added exclude rules - one for every asset in the application - effectively a manifest of all the client side assets. What results is a bloated _routes.json that is actually duplicating work that is already happening in the handling of assets under the hood.

In Workers + Assets, we added a new behaviour, which was that if a request could be handled by an asset then it was by default (the run_worker_first config alters this). The result of this is that for the vast majority of use cases there is no need for a _routes.json at all. For most frameworks, they are happy that we server the static asset directly (and cost-free) if the request matches and otherwise fallback to the User Worker. No need for the user nor the framework to list off all the "API" or "SSR" routes in config.

The reason for this new proposal is that this default behaviour doesn't quite catch a small number of use cases that are still important:

• SPA + REST API: in this kind of application, the user sets not_found_handling to single_page_application in order to benefit from the contents of index.html being returned for all non-asset requests. This works great, except it doesn't allow any routes to be handled by the User Worker. So in light of that the default behaviour here is that in single_page_application mode, all requests that don't match an asset are routed to the User Worker. It is then responsible for handling API request and delegating back to env.ASSETS.fetch() in order to trigger the index.html content handling for non-API and non-asset requests.
• Middleware processing in front of some asset requests: in this kind of application the user doesn't want all requests that match assets to just return the asset but for it to go via the User Worker so that it can do some special pre/post-processing, such as authentication/authorisation of the user. Here the developer must turn on run_worker_first and manage all of this themselves, losing the nice (and free) handling of static assets that don't need to be behind this middleware.

Both of these cases are made cleaner by us implementing _routes.json:

• SPA + REST API: the developer can list their API paths in include rules but still have single_page_application mode turned on. Here those request that match the include rules will always go to the User Worker. The rest just get handled as normal.
• Middleware processing in front of some assets: the developer can list the paths to assets that need to go via the middleware in the User Worker in include rules of _routes.json. Everything else works as normal.

---

The reason for the sentence, below, was to imply that most SSR style frameworks are unlikely to need to add anything to _routes.json.

Note: this proposal would mean that _routes.json becomes a user-facing configuration file, and frameworks should avoid using it for framework-specific purposes

A purely client-side framework also should not be adding to _routes.json since they should not be aware of any backend APIs - this is outside of their scope, and should be handled by the developer.

I can see that if the backend API is being generated from something like Hono then it would be helpful for Hono to provide the include rules that declare what routes it is expecting to handle as API requests.

So while the intent still holds, I think this could be reworded to make it more clear.

[marbemac]

❤️ I love this! Thank you guys so much for listening and putting together this proposal.

Only had two thoughts - once was similar to Isaac, and the second was wether routes definition might make sense in the wrangler.json file? Especially if the intention is that users define it rather than frameworks, handling it in the wrangler file means a) one less file and b) it's more discoverable w schema based autocomplete in most editors, etc.

Either way, very excited for this.

[korinne]

Thanks so much -- we're excited to work with the community more openly :)

We actually did discuss having this in Wrangler config actually -- something like an extra property to the assets block that would accept an array of routes that bypass the assets and go straight to the "User Worker".

We were worried that 1) this wouldn't really make it easier to migrate from Pages and 2) it could make the Wrangler config super unwieldy and 3) every framework would then need to output their own wrangler.json which can result in issues. But, if people are more interested in this being defined in Wrangler config, we are definitely open to it! Would love to hear others' thoughts.

[marbemac]

Yeahh it's not a good option for the framework use case, good point.

[tmm]

Love it! Will the Vite plugin also support _routes.json?

[korinne]

Yes, we'd definitely have this supported in the Vite plugin.

[tmm]

Awesome! The reason I ask is because the Vite plugin does not currently support run_worker_first so good to know _routes.json will be supported.

https://developers.cloudflare.com/workers/vite-plugin/reference/static-assets/#headers-and-redirects

[korinne]

@tmm yes exactly -- this is another reason we want to support _routes.json as it improves the current gaps between the Vite plugin and wrangler dev when it comes to run_worker_first

[arcticmatt]

Small note on the naming—I realize it's meant to be the same as Cloudflare Pages, but I find it fairly unintuitive. I would find it clearer if it were something like

• exclude -> assets_only
• include -> worker_only

[korinne]

Super fair feedback! Thank you!

[remorses]

My feedback would be to continue using the wrangler assets field for templates and tutorials, most apps will only need that.

Also remove the binding field in tutorials code, only add it for workers that use it in advanced use cases, showing this field confuses the reader because it looks like you have to handle static assets yourself in the worker, using a KV binding, which is not the case. This happened to me for example.

Another improvement is to add this detailed documentation in the wrangler json schema description for the assets field, then add the $schema field to all wrangler.jsonc files in documentation and guides.

[korinne]

This is great feedback, thank you!

[benjavicente]

Hi! I am building a small SPA on Cloudflare workers and have some thoughts:

1. I understand that the idea is that frameworks don't include the list of assets on excludes, but, considering that the problem comes from avoiding using the worker, should frameworks generate the list of paths that the worker should be called in includes, to avoid calling it on 404s? Like, for example, a hono app that generates a list of paths it can handle at build time such that it only calls the workers when it really has a route handler attached.
2. Following a similar idea of point (1), how could one express that the worker should only be invoked on certain paths? For example, /api/*and all other paths fall back to not_found_handling without running the worker. It feels that exclude running before include limits this. Setting * in exclude doesn't allow any worker route, and with only api/* in include, the router will be called first on api/*calls, but also when there is an asset miss, for example, will run at /assets/missing.
   If include runs first, the condition of worker runs first only depends on include, so we can use api/* as before, and with * in exclude second, it will send everything else to assets without invoking the worker.
   I added a diagram below that I used to understand that. The problem is on the big blue arrow, if the exlcude runs first, it has the include but not exlcude condition. If it runs seconds, I believe it only has the include condition.

I don't like the naming and that it's a separate file (coming for someone that hasn't created manually a _route.js file), but that's probably fine. Anyway, thanks for making this discussion open and the general effort on making the platform great!

[petebacondarwin]

I think this is what you would get with:

_routes.json

{ "include": "/api/*" }

wrangler.jsonc

{
  // ...
  "assets": { "not_found_handling": "404-page" }
}

[benjavicente]

Ok, I see it, thanks. [Although, the worker could be invoked outside api/* when called outside the browser (without Sec-Fetch-Mode: navigate)]

[petebacondarwin]

Ok, I see it, thanks. [Although, the worker could be invoked outside api/* when called outside the browser (without Sec-Fetch-Mode: navigate)]

This is a very good point; I would say that we could/should consider turning off that Sec-Fetch-Mode feature when there is a _routes.json.

[benjavicente]

But disabling that wouldn't call the Worker on every MISS of Static Assets?

[petebacondarwin]

The behaviour would be:

• if matches _routes.json rules then always go to the Worker
• else if matches asset the respond with the asset
• else if doesn't match a _routes.json rule nor matches an asset, it would be based on not_found_handling:
  • none always hit the Worker if not an asset
  • 404-page always return the nearest 404.html (never to the Worker)
  • single-page-application always return the content of /index.html (never to the Worker)

[mhart]

My high level perspective is that there are two use cases to cover here:

1. Users migrating from Pages
2. Users wanting an SPA, but the ability to just pass particular prefixes (largely just /api) through to the Worker

I think _routes.json makes sense for (1) – but for (2) I think _routes.json is too complicated for most users (and unnecessary to have in a separate file)

I think for (2) all you need is:

  "assets": {
    "directory": "./dist/",
    "not_found_handling": "single-page-application",
    "handle_by_worker": ["/api/"]
  }

Obviously plenty of bike shedding to be had over naming. I think it needs to be something less ambiguous that include or exclude for this property.

• worker_prefixes (or worker_routes)
• api_prefixes (or api_routes)
• dynamic_prefixes (or dynamic_routes)
• handle_by_worker
• passthrough_to_worker

(We already use the term "handle" in "not_found_handling", so one advantage of reusing that is that it makes it less confusing)

[korinne]

Thanks @mhart -- this is something we can definitely do!

Another comment suggested this as well, and I responded with some of the reasons why we didn't initially do this: #9143 (reply in thread)

That being said, if enough people prefer this solution, we are open to doing it all through Wrangler config (it was actually the first idea we discussed).

[marbemac]

handle_by_worker is nice and clear for the primary use case i've seen voiced (the /api use case, as mhart mentioned). Maybe this is separate / in addition to _routes? Issue with just going with everything in the wrangler file, as you mentioned in my original comment, is that having frameworks edit the wrangler file doesn't seem like a great idea.

You guys have more data than we do, but I wouldn't be surprised if the vast majority of folks are covered by a simple and clear handle_by_worker feature - no extra files needed, and the naming is clear. And then the routes json file could still be there for a) pages migration and b) frameworks and edge cases?

[whistlecube]

This would be perfect for my use case, just putting it out there! Thanks everyone!

[BerndWessels]

In the proposal and future documentation, can we please make absolutely clear that the local development environment with the cloudflare vite plugin will behave exactly like the deployed production environment.

It is absolutely crucial that it is crystal clear which request will incur costs and which will be free thanks to cloudflares generous free asset hosting 🙏

Thanks for the great work 🥰

[peterp]

This is really exciting, as a framework author I think this adds a ton of clarity, and we would love to add a set of default rules to our starter projects. My only request is that you also support jsonc so that we can add comments on what our rules are doing; and perhaps point people towards some documentation that helps them understand how to change it.

[lecstor]

I don't have a lot to add except to +1 that all I want right now is to be able to support my oAuth routes and it sounds like this proposal covers that and a lot more. I wasn't even sure about making it a list in my worker-first-paths PR rather than a single prefix as you can always nest more under it. Nearly just went with a hard-coded worker/ path..

Are there documented use-cases for the other scenarios? I can only see run_worker_first for use-cases like gating assets behind authentication. Some solid examples might show the value a bit better.

I'm guessing that I'm just ignorant of the use-cases, but it feels like anything that wouldn't be covered by a simple whitelist of routes to go to the worker could probably be cleaned up so it could and gain other benefits in the process. On the other hand, maybe you just want to make it possible it to support those complex cases.

[BerndWessels]

Is there a rough estimate already when this will be released?

[BerndWessels]

@petebacondarwin Hello, do you have any idea when we can expect the proposal to be implemented?
Thanks

[petebacondarwin]

Hi @BerndWessels - sorry for the radio silence. This is currently being implemented (right now!).
You'll probably see some PRs coming through such as #9304.
I am not sure of official release timelines yet but think weeks rather than months.

[BerndWessels]

@petebacondarwin any news on this? Will there be an announcement here in this git issue once it is released?

[oscabriel]

As someone who has spent the last couple weeks trying desperately to wrap my head around Cloudflare in general and the Vite Plugin specifically, in order to get a starter kit deployed to Workers that combines Cloudflare's React template w/ authentication through Better Auth, I just want to add that I am incredibly excited for this proposal, and welcome any and all increased clarity in the docs about how CF functions behind the scenes. I personally prefer lower-magic solutions, and an option to be more explicit and intentional about what will happen when navigating about my app is appreciated.

I was eventually able to get authentication working using Better Auth's Email OTP plugin, but social OAuth has been a pain, no matter what config tricks I tried. I'm at least happy to KNOW what the problem is now (I learned a lot about how CF has been handling routing so far reading through this proposal), and am eager to adopt the _routes.json config file to get OAuth finally working properly. Big ups to everyone working on this 🤙

[BerndWessels]

If I want to use the cloudflare vite plugin project already without having to wait, but also staying as compatible as possible with the future proposals implementation, I use

wrangler.json:

  "assets": {
    "binding": "ASSETS",
    "run_worker_first": true
  },

And in the worker:

import { Hono } from 'hono'
import { cors } from 'hono/cors'
import { logger } from 'hono/logger'
import { prettyJSON } from 'hono/pretty-json'
import { authMiddleware } from './middleware/auth'
import authRoutes from './routes/auth'
import { createDb } from './db'
import type { Kysely } from 'kysely'
import type { DB } from './db/types'

interface Env {
  ASSETS: Fetcher
  DATABASE_URL: string
}

interface Variables {
  db: Kysely<DB>
}

const app = new Hono<{ Bindings: Env, Variables: Variables }>()

// Initialize database
app.use('*', async (c, next) => {
  c.set('db', createDb(c.env))
  await next()
})

// Middleware
app.use('*', logger())
app.use('*', prettyJSON())
app.use('*', cors())
app.use('*', authMiddleware)

// API Routes
app.route('/api/auth', authRoutes)

// Health check
app.get('/api/health', (c) => {
  return c.json({ status: 'ok' })
})

// Serve static assets and handle client-side routing
app.get('*', async (c) => {
  try {
    // Try to serve the static asset
    const response = await c.env.ASSETS.fetch(c.req.url)
    if (response.status === 200) {
      return response
    }
    // If asset not found, serve index.html for client-side routing
    return c.env.ASSETS.fetch(new URL('/index.html', c.req.url))
  } catch (e) {
    // If anything fails, serve index.html
    return c.env.ASSETS.fetch(new URL('/index.html', c.req.url))
  }
})

export default app

So by the time the proposal is implemented I can just change the wrangler.json and remove the static asset serving from my worker code.

I know that this interim solution invokes the worker on every request, but it enables my OAuth solution to work as expected without major code changes and will only go into production once the proposal is implemented.

Is this OK or am I missing something important?

[Cherry]

My understanding is that run_worker_first should always trigger your worker first, regardless of your not_found_handling config - are you testing locally @marbemac and perhaps hitting this issue with the Vite plugin where run_worker_first isn't implemented yet? #8430

[marbemac]

Ah, yes this is local - I didn't realize it's not implemented yet.

[BerndWessels]

run_worker_first is implemented in the cloudflare vite plugin, isn't it? I am using it right now in the solution I showed here and it works for me.
And @marbemac is right, I experience exactly the same.

Setting "not_found_handling": "single-page-application", seems to cause worker to be skipped for direct browser requests, even with "run_worker_first": true,.

[BerndWessels]

oh no, the vite-plugin 1.1.1 to 1.2.0 is breaking my code :(

#9249

[whistlecube]

run_worker_first is implemented in the cloudflare vite plugin, isn't it? I am using it right now in the solution I showed here and it works for me.

And @marbemac is right, I experience exactly the same.

Setting "not_found_handling": "single-page-application", seems to cause worker to be skipped for direct browser requests, even with "run_worker_first": true,.

It's not implemented yet, there's even a warning on the Vite plugin docs. Hopefully this proposal can solve the issue soon!

[korinne]

Hi all, thanks again for all the valuable feedback on this proposal -- it means a ton. The backend work for supporting more granular routing control is nearly complete, and we now need to finalize how users will configure this.

From the discussion here, a few distinct approaches for user configuration have emerged as the main contenders. We'd like to lay these out and gather your thoughts, before making the final decision:

1. User-Facing _routes.json File

• Users create/manage _routes.json with include/exclude rules (like Pages).
• If a _routes.json file is present and the user has not_found_handling set to single_page_application, we will disable the Sec-Fetch-Mode: Navigate behavior so that only explicit routing determines behavior.
• Considerations: The idea here was to provide a direct migration path for users familiar with _routes.json , but this would make something that was previously generated a user-facing configuration.

2. Routing is configured assets block in Wrangler configuration

• Routing rules defined in Wrangler config

Example (wrangler.jsonc):

{
  // ... other top-level configurations ...
  "assets": {
    "directory": "./public",
    // "not_found_handling": "single-page-application", // etc.
    "handle_by_worker": ["/api/*", "/auth/**"] // Key name TBD
  }
}

• Considerations: Keeps all config centralized in Wrangler config, and is much simpler and more discoverable. This could get unwieldy if too many routing options are added here.

3. Configuration within Wrangler config by evolving run_worker_first

• The existing run_worker_first boolean key could accept an array of path patterns.

Example (wrangler.jsonc):

{
  "assets": {
    "directory": "./public",
    "run_worker_first": ["/api/*", "/admin/**"] // Changed from boolean
  },
}

• Considerations: This is nice because it builds on an existing config key, and clearly signifies that for these paths, the Worker executes before asset serving. However, changing the type and behavior of an existing key might be confusing for existing users.

We're now at a crucial point where we need to decide which of these options (or a close variation) offers the best balance of usability, functionality, and clarity for you. With that, we'd love your thoughts on:

• Which option feels most intuitive for defining routes that invoke your Worker?
• Is it more important to use a _routes.json config file because it's familiar when coming from Pages? In this case though, you'd still need to configure _routes.json yourself to specify the routes to invoke your Worker -- which is a different workflow from Pages.

Thanks again -- we are supporting the ability to more finely specify which routes invoke your Worker, so any feedback on the DX is much appreciated.

[vitaliitrush]

omg, wait for it!

[korinne]

Alright, thank you everyone for your feedback -- it's been incredibly helpful for us! Based on the discussion, we've decided to go with Option 3 . Evolving run_worker_first is a nice, intuitive way to configure which routes invoke your Worker, and also helps make the config option more useful.

For example, here's how this could look in wrangler.jsonc:

{
  "assets": {
    "directory": "./dist",
    "not_found_handling": "single-page-application",
    "run_worker_first": [
      "/api/**",      // API calls go to Worker first
      "!/api/docs/**"    // EXCEPTION: For /api/docs/**, try static assets first
    ]
  },
}

Thanks again, and we're excited to get this out to you shortly!

[Cherry]

Very glad to see a path moving forward here!

What's the plan with addressing one of the original big concerns here, with migration from Pages and frameworks that generate _routes.json today? Is the intent that frameworks now edit the user-facing wrangler.jsonc programmatically? Or output their own wrangler config? Or just advise users on how to configure their own configs?

[BerndWessels]

@korinne Just to confirm, this change will not have any impact on using our own custom domains, right?
Or in other words, the new behavior will work as intended with custom domains too, right?

Great to see it release soon, great work

[korinne]

@BerndWessels Correct -- the array of paths will not impact the use of custom domains. Custom domains determine if and when your Worker is invoked for a given incoming request (the initial routing) Whereas assets.run_worker_first config dictates behavior within your Worker, after it has already been invoked (internal routing).

[korinne]

Hi all, an exciting update!
Advanced routing control is finally here. You can now explicitly define which routes invoke your Worker script in Wrangler configuration via run_worker_first :

For example:

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

Advanced routing control is supported in:

• Wrangler v4.20.0 and above
• Cloudflare Vite plugin v1.7.0 and above

Docs

• Documentation for using run_worker_first for Single Page Applications
• General documentation for invoking your Worker on selective paths

Thank you all SO much for working with us on this, and helping us design the right solution. Definitely try it out and let us know of any issues you run into.

[tmm]

Upgraded yesterday and love it! Thanks for listening to and running with the feedback quickly.

[BerndWessels]

Great work, thank you.

[achesui]

Excelent!

[sibi361]

Hi we are in the process of porting our Astro.js website which is currently on Cloudflare Pages to Cloudflare workers by using the @astrojs/cloudflare plugin and are facing a issue w.r.t how cloudflare static asset routing which is shooting up our overall workers bill.

Being a static site generator, Astro.js outputs index.html files for every webpage on our site. Requests to these static webpages are correctly served by the assets handler and the rest trigger the worker script (which is compiled by the @astrojs/cloudflare plugin) located at ./dist/_worker.js/index.js.

---

Our use case requires the use of Astro's Middleware feature to run on specific routes. Since the middleware's default behaviour is to run on all routes, a worker invocation is triggered on every request that does not match a static asset, i.e. a index.html file which includes:

A) Routes that we want to hit the middleware e.g. /oauth/callback
B) Non-existent routes leading to a 404 not found error

As of now, there is no provision in the Astro middleware to run on specific routes, like on other frameworks such as Next.js.

---

Case B) is causing thousands of worker invocations on our current staging Astro website. The majority of these requests are coming from malicious bots and crawlers looking for sensitive files such as .env, .htaccess, etc. We believe that these invocations are going to shoot up our Cloudflare Workers bill once we move this website to production.

Hence we are trying to find a solution that allows the Astro middleware worker script to run only on Case A), i.e. only on explicitly whitelisted paths.

---

In light of this issue, we have been closely following this proposal. Since it was merged, we have been trying make it work towards the above mentioned use case but haven't got any progress yet.

Here is one of the only combinations of the html_handling and run_worker_first asset config options in the wrangler config which seemed to show a behavioral change in the static asset/worker script routing:

    "assets": {
        "binding": "ASSETS",
        "directory": "./dist",
        "html_handling": "force-trailing-slash",
        "run_worker_first": ["!/*", "/oauth/callback"]
    }   

Before: worker would run on every route for which asset not found, including 404

Now: Worker is never invoked and an empty no-body 404 response is returned if no asset is found. This happens even on sending a request to /oauth/callback for which there is no index.html asset present.

Reasoning: The negative !/* rule which is intended to prevent worker invocation on not found requests seems to be taking higher precedence that the positive rule.

Intended: Worker script should (only) get invoked if the request path matches /oauth/callback.

I think we want positive rules to have higher precedence over negative rules but the current implementation is the other way around. We would be glad if you could point us towards an asset config that might help us achieve our use case.

---

We also experimented with the dist/_routes.json file since apparently this Cloudflare Pages only feature has now come to Cloudflare Workers.

This is the config we tried but it doesn't seem to be doing anything:

{ "version": 1, "include": ["/oauth/callback"], "exclude": ["/*"] }

[jamesopstad]

@sibi361 I think using "not_found_handling": "404-page" would fit your use-case. So your config would look like this:

    "assets": {
        "directory": "./dist",
        "html_handling": "force-trailing-slash",
        "not_found_handling": "404-page",
        "run_worker_first": ["/oauth/callback"]
    }   

You can then also provide a custom 404.html page if you like. Does that work for you?

[sibi361]

@jamesopstad I tried the config given by you but it failed to satisfy our use case. Here are the 2 cases I tried:

Case 1: Did not provide a custom 404.html
The worker is invoked on every request that doesn't match a static asset. This includes 404 not found requests.

Case 2: Provided a custom 404.html
If the request does not match a static asset, the provided 404 page is returned. The worker does not get invoked, neither on these 404 requests nor on the paths provided via run_worker_first.

[jamesopstad]

@sibi361 You do need the 404.html so Case 1 won't work (sorry for suggesting that wasn't necessary). Case 2, however, should work. Please can you check you are using a version of Wrangler more recent than 4.20.0 (when this feature was introduced) and open an issue if this is not resolved. Thanks.

[sibi361]

@jamesopstad Thank you for the clarification. I am on Wrangler 4.23.0 and case 2 is not working.

Will attempt to replicate it in a minimum reproducible example without the @astrojs/ cloudflare adaptor and file an issue if this persists.

$ npm show wrangler   

[email protected] | MIT OR Apache-2.0 | deps: 8 | versions: 4776
Command-line interface for all things Cloudflare Workers
https://github.com/cloudflare/workers-sdk#readme

keywords: wrangler, cloudflare, workers, cloudflare workers, edge, compute, serverless, serverless application, serverless module, wasm, web, assembly, webassembly, rust, emscripten, typescript, graphql, router, http, cli

bin: wrangler, wrangler2

dist
.tarball: https://registry.npmjs.org/wrangler/-/wrangler-4.23.0.tgz
.shasum: 67bd967b6aebf734f2e3b6b9fdfe3e88935cbb34
.integrity: sha512-JSeDt3IwA4TEmg/V3tRblImPjdxynBt9PUVO/acQJ83XGlMMSwswDKL1FuwvbFzgX6+JXc3GMHeu7r8AQIxw9w==
.unpackedSize: 9.0 MB

dependencies:
@cloudflare/kv-asset-handler: 0.4.0
@cloudflare/unenv-preset: 2.3.3
blake3-wasm: 2.1.5
esbuild: 0.25.4
miniflare: 4.20250617.5
path-to-regexp: 6.3.0
unenv: 2.0.0-rc.17
workerd: 1.20250617.0

maintainers:
- wrangler-publisher <[email protected]>

dist-tags:
beta: 0.0.0-66edd2f3b
d1: 0.0.0-e4c703ba
dispatch-namespaces-dev: 0.0.0-cdaa58d13
latest: 4.23.0
legacy-beta: 0.0.0-6e09672d2
legacy: 3.114.10
next: 0.0.0-f7c347a67
pages: 0.0.0-96e612b
using-keyword-experimental: 0.0.0-d27c287a
v4-rc: 4.0.0-rc.0
wasm: 0.0.0-c0d7699
workflows: 0.0.0-6379a9ae6
[email protected]: 2.2.4
xab-dev: 0.0.0-0ed00bc97

published 2 days ago by wrangler-publisher <[email protected]>```

[sibi361]

Now I am pretty certain it has something to do with how the @astrojs/ cloudflare adaptor handles 404 requests, because when I attempted to replicate case 2 without the adaptor on a barebones worker, it worked flawlessly.

Thanks for the support! @jamesopstad