Hydration error on direct navigation to non-root routes in SPA mode

[bbertold]

Which project does this relate to?

Start

Describe the bug

When deploying a TanStack Start application with spa mode enabled to Cloudflare, directly navigating to a non-root route (e.g., /example) results in a React hydration error. The same route works correctly when accessed via client-side navigation (e.g., clicking a <Link> from /).

On direct navigation to a non-root route, React throws a hydration mismatch error and the page visibly flashes:

Hydration failed because the server rendered HTML didn't match the client. 
As a result this tree will be regenerated on the client.

Error reference: https://react.dev/errors/418?args[]=HTML&args[]=

This issue appears to be directly related to Cloudflare's SPA handling configuration:

"not_found_handling": "single-page-application"

Your Example Website or App

https://github.com/bbertold/tanstack-start-spa

Steps to Reproduce the Bug or Issue

1. Clone the reproduction repository
2. Build the application: pnpm build
3. Preview the build: pnpm preview
4. Open browser and navigate directly to /example in the URL bar
5. Press Enter
6. Observe the hydration error in console and visible flash of content

Expected behavior

The page should load without hydration errors.

Screenshots or Videos

No response

Platform

• Router / Start Version: 1.154.8
• OS: macOS
• Browser: Chrome (144.0.7559.59)
• Bundler: Vite (7.1.7)
• Wrangler version: 4.60.0

Additional context

No response

[pablor21]

I'm facing the same error, with caddy as a server. Only happens, as @bbertold says, wen navigating directly to a child route, not on client side navigation.

[Kyujenius]

Hi @bbertold and @pablor21!

I've been looking into this issue and recently submitted a PR (#6481) that I hope might help resolve this.

From my analysis, it seems the root cause is that in SPA mode, servers (like Cloudflare or Caddy) serve the root index.html (the shell) for all direct navigations to child routes. React then tries to hydrate this root HTML as if it were the specific child route's content, which causes the mismatch error and the visible flash.

In the PR, I've proposed a small fix that:

Injects a marker (window.TSS_SPA_SHELL) into the SPA shell during build. Note: I adopted the window._TSS* naming convention already used in the codebase (e.g., window.TSS_START_OPTIONS) to ensure consistency with the existing architecture.
Allows the client to detect this marker and safely skip hydration if the path doesn't match, performing a fresh client-side render instead.
This approach should be server-agnostic, addressing the issues reported for both Cloudflare and Caddy setups.

Thank you

[bbertold]

Hello all! Thanks for the info @Kyujenius and @pablor21! I removed Cloudflare from the issue title as it affects other deployment targets. I also updated the repro repo as well with more instructions on how to reproduce the issue. Thank you for the analysis @Kyujenius, it makes a lot of sense, hope to see it get merged!