SPA mode in Wrangler SDK not every calling Worker Handler

[matthew-sessions]

Which Cloudflare product(s) does this pertain to?

C3 (npm create cloudflare)

What versions & operating system are you using?

Wrangler 4.7 Node 20

Please provide a link to a minimal reproduction

efda570#diff-d440230b8105b8dee550032dd0c64939a6727564b8617dc8f77ae9af4cd982b2

Describe the Bug

Using the CLI to create a React APP for workers with Assets never invokes the Fetch Handler.

Steps to reproduce:

1. Create a project by following docs: https://developers.cloudflare.com/workers/frameworks/framework-guides/react/
2. Deploy
3. Navigate to API path

The Fetch handler to returns JSON is never invoked.

efda570#diff-d440230b8105b8dee550032dd0c64939a6727564b8617dc8f77ae9af4cd982b2

This behavior is contrary to the docs: https://developers.cloudflare.com/workers/frameworks/framework-guides/react/

Please provide any relevant error logs

No response

[Cherry]

I responded in Discord, but for reference here this is due to the assets_navigation_prefers_asset_serving compat flag. This is really unintuitive behaviour. I completely understand technically why it works the way it does - it's very "smart". But this isn't intuitive to how most people treat the web and their applications - people don't expect different behaviour with a fetch to a URL vs hitting it in their browser.

If you open your browser console and run await (await fetch('/api/hello')).json(), you'll see the expected response, and the Worker get invoked. But just hitting the endpoint /api/hello for testing as is detailed here, serves the index.html.

I wonder if some more detailed debug logging around SPA mode or something would really help people understand how SPA mode + assets_navigation_prefers_asset_serving operates. As a workaround for folks hitting this, you can add assets_navigation_has_no_effect to your compatibility_flags to get the previous (and in my opinion more expected) behaviour.

[threepointone]

I want to push back here, I contend that this is how SPA mode is meant to operate, and it was a miss that we didn't ship this in the first iteration. Very simply, "single page mode" means: if you open a URL in your browser, and there isn't a static asset that matches that path, then load the closest index.html. There are no legit user facing reasons that a URL opened in a browser tab should output json with single page mode. Note that you can make a fetch request normally and it'll return the json at that endpoint (if you setup a worker to respond with json to that request). Also note that it's impossible to make a fetch request from the browser with a manual Sec Fetch Mode header, browsers don't allow it to happen in userland.

If you don't want this behaviour, then you're still free to disable single page mode, have the worker handle api and assets requests.

[Cherry]

There are no legit user facing reasons that a URL opened in a browser tab should output json with single page mode.

While I agree technically, and think the implementation here is very “smart”, it’s just not intuitive to how people develop or understand the web. No one expects to get a different response when they hit an API endpoint in their browser vs via fetch, and they haven’t for decades.

At bare minimum here, some logging needs to be added to convey to the user what is happening - right now it feels like very difficult to track down magic. Even if this is the technically and objectively right choice for the thing to do (which I would still argue), the discussions here and in the discord show it’s very clearly not intuitive or understood. cc @GregBrimble

I’m also still not sure why this was enabled so quickly (around 10 days from flag -> default) with no documentation or education to accompany it, but that’s a different discussion.

[threepointone]

Yeah, we'll update docs. I'm not sure we have to add additional logging; it's a regular static asset load. Where and what should we log so that it's not noisy beyond the first initial understanding of how it behaves?

No one expects to get a different response when they hit an API endpoint in their browser vs via fetch

This is how single page apps are expected to work, Content negotiation is indeed decades old. https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Content_negotiation

I'm not going to consider this magic, the header's designed for this use case and the behaviour is an overall win (the best part being you don't get charged for those requests/worker invocations anymore, compared to the previous iteration).

[matthew-sessions]

@threepointone thanks for the additional context. The confusion for me was the fact that assets were previously served via the fetch handler and the API was hit regardless of set headers.

Love this feature tbh. Seems very clean.