Routing Conflict with `@cloudflare/vite-plugin` in React SPA

[werkamsus]

Which Cloudflare product(s) does this pertain to?

Vite Plugin

What versions & operating system are you using?

wrangler: ^4.7.0, vite: ^6.1.0, @cloudflare/vite-plugin: ^1.0.2, hono: ^4.7.5, react: ^19.0.0 (Node.js: unknown, C3: unknown)

Please provide a link to a minimal reproduction

No response

Describe the Bug

Routing Conflict with @cloudflare/vite-plugin in React SPA

When using the @cloudflare/vite-plugin in a React SPA setup—such as the vite-react-template or any custom project following a similar structure—a routing conflict occurs when attempting to directly navigate to server-side API routes via the browser.

Problem Description

This happens because the SPA fallback behavior (enabled by setting "not_found_handling": "single-page-application" in wrangler.json) intercepts requests with Sec-Fetch-Mode: navigate before the Worker script executes. As a result, the SPA’s index.html is served even for intended API routes.

This breaks scenarios where API routes need to be reachable directly from the browser, such as:

• OAuth callbacks (e.g., /api/auth/callback/...)
• Server-initiated redirects to API endpoints

Note: Programmatic fetch calls from the SPA to /api/* routes still work as expected, since they use cors mode and do reach the Worker.

---

Use Case / Impact

This breaks critical server-side functionality that relies on direct browser interaction with API routes, including:

• OAuth callback handling from providers like Google or GitHub
• Redirect-based flows where the browser is expected to land on a server-side route

---

Steps to Reproduce (Conceptual)

1. Set up a project using either the vite-react-template or a custom project using @cloudflare/vite-plugin with Hono.
2. Define a simple API route in Hono:

   app.get('/api/test', (c) => c.text('API OK'))

3. Deploy using default or SPA-configured wrangler.json.
4. Attempt to visit https://<your-worker-url>/api/test directly in the browser.

Expected Behavior

The API handler should respond with API OK.

Actual Behavior

The SPA’s index.html is served instead, and the Hono route is bypassed.

---

Troubleshooting / Workarounds Attempted

1. Changing not_found_handling

   • Switching to "404" allows API routes to work
   • But breaks SPA routing
   • Requires manually serving index.html from Hono, which adds complexity

2. Using run_worker_first

   • Setting run_worker_first: true along with SPA fallback and a valid assets config does allow the Worker to run first
   • But for the SPA to still work, a catch-all fallback route is needed in Hono like:

     app.get('*', (c) => c.env.ASSETS.fetch(c.req.raw))

   • This pattern is not included in the default template and isn’t obvious unless you read deeper into the docs

3. Header Workarounds

   • Attempted to handle requests based on Sec-Fetch-Mode
   • But routing decisions are made before reaching the Worker

---

Question / Suggestion

What’s the recommended approach for using @cloudflare/vite-plugin with React (whether using the vite-react-template or a custom setup) to support both SPA behavior and direct browser access to API routes?

If the correct pattern is:

• run_worker_first: true
• not_found_handling: "single-page-application"
• A proper assets config
• A final catch-all Hono route to serve assets

...could this be documented more clearly or baked into the template directly?

Many full-stack use cases will hit this routing issue, and the workaround isn’t obvious without digging.

---

Environment

• wrangler: ^4.7.0
• @cloudflare/vite-plugin: ^1.0.2
• vite: ^6.1.0
• hono: ^4.7.5
• react: ^19.0.0
• node: [e.g., 20.x.x]

---

Thanks for maintaining these tools and templates!

Please provide any relevant error logs

No response

[jamesopstad]

Thanks for the issue. This also relates to the discussion in #8798. Could you elaborate a bit more about the section below:

Use Case / Impact
This breaks critical server-side functionality that relies on direct browser interaction with API routes, including:

OAuth callback handling from providers like Google or GitHub
Redirect-based flows where the browser is expected to land on a server-side route

It would be good to have some concrete examples of scenarios that are not supported with the default setup.

[werkamsus]

Thanks @jamesopstad, really appreciate you jumping in.

To clarify, this specifically affects any callback-style redirect from an external page like an OAuth provider, since those can only be loaded via browser navigation and not fetch. In my case, this broke the auth flow.

To keep the Vite plugin config clean, I worked around it by adding a clientside catch-all route in /api/* that serves the SPA. From there, the client makes a fetch call to the actual API endpoint. That way, the browser lands on a valid route and the logic runs clientside.

This pattern is common in fullstack frameworks like Next.js, TanStack Start, SolidStart, and SvelteKit, where exposing API routes to the browser is expected behavior. Would be great to surface this workaround more clearly in the docs or template.

[jamesopstad]

Thanks. This won't be an issue in full-stack frameworks because the not_found_handling in those cases would be set to none (the default value) and Sec-Fetch-Mode behaviour won't be invoked. On first impression, I would have thought that in an SPA you would implement the callback-style redirect client side, which sounds like what you've done. Would love to see a reproduction of the issue.

For context, the main motivation for the Sec-Fetch-Mode behaviour is that, for SPAs, you don't hit your Worker on every navigation.

[marbemac]

I would have thought that in an SPA you would implement the callback-style redirect client side

In the github login example - it's github itself that is redirecting.

1. User clicks login with github
2. Browser loads github.com/xyz for the user to confirm the want to install/authorize the oauth app
3. Github redirects the browser to the callback url - something along the lines of http://localhost:3001/api/auth/callback/github?code=xxx&state=xxx
4. The backend server - worker in this case - needs to process that request. But we cannot atm since worker doesn't see the request - goes straight to the SPA.

Although yeah I suppose could add a route to the frontend at /api/auth/callback/$provider and, on mount, make a get request in the browser to itself to actually hit the worker.

[werkamsus]

@marbemac I only tried some half-baked workarounds I pieced together through CF docs. None really worked though except for this clientside fetch / redirect. Uses betterauth and tanstack router. Didn't ship this so no clue if it's secure / robust enough for prod.

…

-- Nick Raziborsky

On Apr 11, 2025 at 11:54 PM +0200, Marc MacLeod ***@***.***>, wrote: @werkamsus what do you mean by "A proper assets config"? I've tried setting run_worker_first and not_found_handling: "single-page-application" and top level requests still seem to be skipping the worker 🤔. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: ***@***.***> marbemac left a comment (cloudflare/workers-sdk#8879) @werkamsus what do you mean by "A proper assets config"? I've tried setting run_worker_first and not_found_handling: "single-page-application" and top level requests still seem to be skipping the worker 🤔. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: ***@***.***>

[typedrat]

This problem is even worse for workers that return types other than HTML! I'm using a worker to expose a R2 bucket full of images, and there's just no way to make it work. I'd just expose the bucket as a subdomain and access it that way, since I don't need any extra logic, but that won't work with local development.

[BerndWessels]

Got exactly the same issue and it caused 1 degree in global warming due to all the queries to AI I made - only to finally give up and look at the Github Issues :(

I also use OAuth flows

1. client press "login with google" redirects browser to /api/auth/login (which now fails using the cloudflare vite plugin)
2. worker creates oauth url for google and redirects to it
3. google redirects to my /api/auth/google/callback.html endpoint (which would also fail using the cloudflare vite plugin)
4. worker does some user stuff, sets session cookie and redirects to my logged in page

typical standard flow for all oauth providers like google, microsoft, git, facebook, ...

works fine with the old cloudflare worker in combination with cloudflare pages

but screwed up as described by original issue with cloudflare vite plugin :(

And to reproduce, you don't need an elaborate example - just add a /api/hello route in the worker returning <h1>hello</h1> and try then to navigate to it in the browser - this fails :(

So at least for anything requiring OAuth flows this is a showstopper for cloudflare vite plugin - and it should be at least documented somewhere !

Hope there will be a fix for this, since in general I love the new cloudflare vite plugin setup.

BTW would be also cool if the docs would make clear that static assets are still free of charge in this setup - or scenarios in which that might not be the case.