TanStack Router follow-up: remove dependency on internal router.ssr flag

[justin808]

Summary

TanStack Router SSR support merged in PR #2516 and now correctly uses the public async router.load() API.

However, the current server-side helper still depends on a private/internal TanStack Router behavior:

• router.ssr = true in packages/react-on-rails-pro/src/tanstack-router/serverRender.ts

Why This Is Still Fragile

This flag is not part of the standalone TanStack Router public contract. It is currently used to avoid client-only Suspense / initial-load behavior that can cause hydration mismatches, but it still creates an upgrade risk:

• TanStack could change or remove the behavior in a minor or patch release.
• React on Rails would only discover the breakage at runtime after upgrade.
• The current helper includes a runtime assertion, but that only makes the failure clearer; it does not remove the compatibility risk.

Current State

The previous __store.setState() workaround is gone, which is good.

The remaining follow-up is specifically to remove or reduce the dependency on the router.ssr flag.

Proposed Follow-up

1. Track / advocate for a public TanStack Router API for this behavior (for example a skipInitialLoad-style option or equivalent hydration-safe SSR mode).
2. Replace router.ssr = true once TanStack exposes a supported public alternative.
3. Until then, keep compatibility guidance explicit in docs and consider tightening the supported-version guard if needed.

Related

• PR #2516
• Issue #2298

[justin808]

Deep-dive triage pass (2026-03-22):

• Domain: core/runtime
• Labels/Priority signals: (none)
• Current PR coverage: no open PR currently linked
• Proposed next step: add this to the new triage PR stack so it has explicit implementation ownership.

Question: Do you want this scheduled in the next implementation wave, or parked until after active release work?