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!

[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?

[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?