Review

The fix is well-motivated and the approach — using RouterProvider directly instead of RouterClient — correctly resolves the structural hydration mismatch. The code is clearly documented and the deprecation of RouterClient is handled cleanly. A few things worth addressing before merge:

Issues flagged inline

1. Direct mutation of matchRoutes() return values (line 87–92) — match objects are mutated in-place before being handed to __store.setState. If a future TanStack Router version returns references to internal state objects rather than clones, this corrupts state before the setState. Prefer immutable transform inside the setState updater.

2. router.ssr not cleared on render-phase exception (line 104) — the flag is set synchronously during render but is only cleared inside useEffect → .finally(). A throw during render means useEffect never runs, leaving router.ssr permanently set and blocking the Transitioner on all future navigations. A try/finally around the block or explicit documentation of the risk would help.

3. .finally() and the cancelled flag (line 142–147) — minor clarity issue: the cancelled flag guards only .catch, not .finally. Since each mount creates a fresh router instance there's no cross-instance leak, but a comment explaining why this is safe would prevent future confusion.

4. _RouterClient: unknown weakens the public API type (line 179) — restoring the original ComponentType<{ router: TanStackRouter }> | undefined keeps callers type-checked while still signalling the parameter is intentionally ignored.

Not in the diff but worth a follow-up

• types.ts line 105: the JSDoc on DehydratedRouterState.ssrRouter still says "used by RouterClient hydration" — now stale since that path is deprecated.
• TanStackSsrRouterState and TanStackSsrMatch are exported but no longer consumed by any code in this package. Consider marking them @deprecated or noting they're kept only for consumers who may be serialising the wire format.

Reliance on private APIs

The use of router.__store.setState and router.matchRoutes as internal APIs is a necessary trade-off given that RouterClient is broken for this use case. The version guard (>=1.139.0) and the explicit error message provide reasonable protection. It would be worth adding a note to the pro changelog / upgrade guide so users know to re-test after any @tanstack/react-router minor bump.

Overall the change is solid — the four inline items above are the main blockers.

Walkthrough

Client hydration for TanStack Router now relies on a dehydrated payload (__tanstackRouterDehydratedState), computes and injects matches synchronously into the router store, temporarily sets router.ssr during initial load, clears it after router.load() settles, and always mounts RouterProvider (no RouterClient-based hydration).

Changes

Sequence Diagram(s)

sequenceDiagram
  participant Server as Server
  participant Browser as Browser
  participant Dehydrated as DehydratedState
  participant Router as Router
  participant Store as Store
  participant Provider as RouterProvider

  Browser->>Dehydrated: read __tanstackRouterDehydratedState
  alt Dehydrated payload present
    Browser->>Router: router.matchRoutes(router.state.location)
    Router-->>Browser: sync matches
    Browser->>Dehydrated: read ssrRouter.matches (optional)
    Browser->>Router: rehydrate match IDs and overlay server fields
    Browser->>Store: router.__store.setState({ status: "idle", resolvedLocation, matches })
    Browser->>Router: set temporary router.ssr
  end
  Browser->>Provider: mount RouterProvider with router
  Provider->>Router: router.load()
  Router-->>Browser: load settles
  Browser->>Router: clear temporary router.ssr (if still present)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Remove dependency on internal TanStack Router router.ssr flag #2833 — modifies the same TanStack Router hydration codepaths and router.ssr handling; likely directly related.

Poem

🐰 I nudged old globals into the ground,
I stitch server matches, one leap, then bound,
Provider plants roots where Client will wake,
Store turns idle, pending dreams to take,
Hop—hydrate—snuggle bugs away, and celebrate.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Greptile Summary

This PR fixes a React hydration mismatch caused by RouterClient wrapping RouterProvider in <Await> (which suspends on first render) while the server renders RouterProvider directly. The fix switches the client to use RouterProvider directly and synchronously injects route matches via TanStack Router's internal router.matchRoutes() + router.__store.setState() APIs, mirroring the pattern in TanStack Router's own ssr-client.js.

Confidence Score: 5/5

Safe to merge — all remaining findings are P2 style/robustness suggestions that don't affect correctness on the current code path.

The core fix is well-reasoned, production-tested, and the three inline comments are all P2: an in-place mutation that works today but could be fragile in future TanStack Router versions, a cross-instance race on router.ssr that is vanishingly unlikely in practice, and a missing pre-check for user-set router.ssr values. None of these represent a present defect in the shipped code.

clientHydrate.ts — uses internal TanStack Router APIs (__store, matchRoutes); worth re-testing if @tanstack/react-router is upgraded past 1.139.x.

Important Files Changed

Sequence Diagram

sequenceDiagram
    participant Server
    participant Client
    participant Router
    participant ReactDOM

    Server->>Router: createRouter() + router.load()
    Server->>ReactDOM: renderToString(<RouterProvider router={router}>)
    Server-->>Client: HTML + dehydratedState (__tanstackRouterDehydratedState)

    Client->>Router: createRouter() + router.update({ history: browserHistory })
    Client->>Router: router.matchRoutes(location) → matches[]
    Note over Client,Router: Override pending→success on all matches
    Client->>Router: router.__store.setState({ status:'idle', resolvedLocation, matches })
    Client->>Router: router.ssr = { manifest: undefined }
    Client->>ReactDOM: hydrateRoot(<RouterProvider router={router}>)
    Note over ReactDOM: Tree matches server HTML ✓

    ReactDOM-->>Client: Mount complete (useEffect fires)
    Client->>Router: router.load()
    Router-->>Client: load settled (.finally)
    Client->>Router: router.ssr = undefined
    Note over Client,Router: Transitioner re-enabled for navigation

_{Reviews (1): Last reviewed commit: "Fix TanStack Router SSR hydration mismat..." | Re-trigger Greptile}

size-limit report 📦

Review: Fix TanStack Router SSR hydration mismatch

The core approach here is sound and well-reasoned. Using RouterProvider directly instead of RouterClient to avoid the <Await>/defer() suspension mismatch is the correct fix, and the synchronous match injection before first render mirrors TanStack Router's own internal hydration contract.

A few issues worth addressing before merge:

Bug: router.ssr is unconditionally cleared in .finally()

The old code guarded this with didSetLegacySsrFlagRef.current to only clear router.ssr if this module set it. The new .finally() block clears it unconditionally:

if (!cancelled) {
  router.ssr = undefined;  // clears user-set router.ssr too
}

If a user's createRouter() sets router.ssr themselves (e.g. for TanStack Start compatibility), the if (!router.ssr) guard on line ~150 correctly preserves it — but the .finally() will still clear it after the first router.load(). The didSetSsrFlagRef tracking should be restored to guard this.

Bug: Error message version constraint doesn't match peerDependencies

The validation error says >=1.139.0 but peerDependencies specifies >=1.139.0 <2.0.0. These should match to avoid misleading error messages.

Design concern: Internal APIs required in public interface

matchRoutes and __store.setState are private TanStack Router internals. Making them required (non-optional) in the TanStackRouter interface is a semantic breaking change for users who mock or stub the router in tests. Consider:

• Making them optional (matchRoutes?, __store?) with graceful degradation, or
• Moving them to a separate internal interface not exported as part of the public API contract.

Missing test coverage

The buildRouter() mock in tanstackRouter.test.ts does not include matchRoutes or __store, so the existing tests that pass __tanstackRouterDehydratedState will hit the validation throw at runtime rather than exercising the hydration path. New tests should:

1. Add matchRoutes and __store.setState mocks to buildRouter()
2. Verify applyDehydratedMatchData is called and route match data is injected correctly

Minor: applyDehydratedMatchData O(n×m) lookup

The Array.find inside Array.map is fine for typical route trees, but a Map keyed by rehydrated ID would be cleaner and O(n+m) if match counts grow. Not a blocker, just a note.

Address-review run for PR #2932.
Scan window: full PR history (no prior checkpoint marker), triaged feedback from 2026-04-03T16:37:31Z to 2026-04-03T16:51:40Z.
Mode: default cutoff behavior (no check all reviews override).

Mattered

• [Addressed] Preserved user-provided router.ssr ownership during hydration cleanup. Implemented didSetSsrFlagRef tracking and conditional cleanup; added regression coverage for preconfigured router.ssr preservation after post-hydration load. (commit 24a6b93d3)
• [Addressed] Added render-phase hydration error handling so temporary SSR flags created by this module are cleared before rethrow.
• [Addressed] Avoided public type-surface break by making TanStackRouter.matchRoutes and __store optional in the exported interface; hydration internals are asserted locally after runtime checks.
• [Addressed] Aligned runtime version guidance with peer dependency range: @tanstack/react-router >=1.139.0 <2.0.0.
• [Addressed] Clarified ssrRouter as a legacy compatibility payload and documented why it is still serialized.
• [Addressed] Added/updated focused TanStack Router tests for hydration behavior and router.ssr lifecycle.

Skipped

• Direct-mutation warnings were skipped because current code already applies immutable match mapping before setState.
• .finally() race/clarity nits were skipped as non-blocking; current code already guards with !cancelled and includes explicit intent comments.
• _RouterClient typing warning was skipped as already addressed in the existing signature.
• “Rehydrate from payload” warning was skipped as outdated; current hydration applies ssrRouter.matches via applyDehydratedMatchData.
• Status-only bot posts (size-limit / run metadata) were skipped as non-actionable.

No follow-up issue was created.

Future full-PR scans should start after this comment unless check all reviews is explicitly requested.

Review

The core fix is correct and well-explained: replacing RouterClient (which wraps RouterProvider in <Await>/defer()) with RouterProvider directly eliminates the structural server/client mismatch. The synchronous match injection via matchRoutes + __store.setState mirrors what TanStack Router's own hydrate() does internally, which is the right approach. The deprecation of RouterClient is handled cleanly.

Three items flagged inline. One broader concern worth discussing:

SSR payload size: double-serialization of loader data

serverRender.ts now emits both ssrRouter (short-key match payload built by buildSsrRouterState) and dehydratedRouter (from router.dehydrate()). clientHydrate.ts reads ssrRouter.matches[].l to restore loader data during hydration. In many apps these two payloads will contain the same loader data — serialized twice in the SSR HTML.

For apps with large loader payloads this doubles the wire weight. Since ssrRouter is now the authoritative source for match-data restoration on the client, consider whether dehydratedRouter still needs to be sent (or vice versa). If both are needed for different reasons (e.g. dehydratedRouter for user-defined router.hydrate() callbacks and ssrRouter for match injection), a comment in serverRender.ts explaining why both exist would prevent a future maintainer from "deduplicating" them incorrectly.

Minor: exported SSR wire-format types lack deprecation markers

types.ts line 108 now describes ssrRouter as a "legacy" field, but the exported TanStackSsrRouterState and TanStackSsrMatch interfaces themselves have no @deprecated marker. Since they're exported, marking them or adding a note that they represent an internal wire format would signal to library consumers not to build their own serializers against them.

All review feedback has been addressed across commits fa30ceb and 24a6b93:

Addressed in code:

• router.ssr cleanup now guarded with didSetSsrFlagRef ownership tracking — only clears when this module set it
• Error message version constraint updated to match peerDependencies (>=1.139.0 <2.0.0)
• matchRoutes and __store made optional in public TanStackRouter interface, with a separate TanStackRouterHydrationInternals intersection type for internal use
• try/catch added around hydration block as safety net for render-phase exceptions
• Cross-instance interference comment already present in code

Already correct (no change needed):

• Match objects already use immutable spread patterns throughout — no in-place mutation
• if (!router.ssr) guard preserves user-set values from createRouter()
• applyDehydratedMatchData already hydrates from server payload (loaderData, beforeLoadContext, status, errors, SSR flags)
• _RouterClient parameter already typed as ComponentType<{ router: TanStackRouter }> | undefined

All 12 review threads have been resolved.

Review: Fix TanStack Router SSR hydration mismatch

The root cause analysis is correct and well-documented — replacing RouterClient (which suspends on first render via Await/defer()) with direct RouterProvider usage is the right fix. The test suite is thorough and the regression tests directly prove the failure mode. A few issues to address:

Required: Missing CHANGELOG entry

This is a user-visible bug fix affecting SSR behavior. Per project guidelines, a [Pro]-tagged entry under Fixed is needed.

Issue 1: O(n x m) linear search in applyDehydratedMatchData (clientHydrate.ts:142)

The ssrMatches.find() call inside matches.map() rehydrates every SSR match ID for each client match lookup. For a deep route tree this compounds. A pre-built Map keyed by rehydrated ID would be O(n+m) instead.

Issue 2: Async router.options.hydrate errors are silently swallowed (clientHydrate.ts:309-316)

hydrationCallbackPromiseRef is constructed with a .catch that only logs, so it always resolves. runPostHydrationLoad therefore proceeds to router.load() even when the user hydration callback failed. If the callback populates a query cache (TanStack Query etc.), silently continuing means the page renders with missing cache data and no error boundary fires.

Issue 3: routeId vs. id asymmetry between preload and match injection

preloadMatchedRouteChunks looks up routes via match.routeId -> looseRoutesById[routeId], while applyDehydratedMatchData matches by m.id. TanStack Router distinguishes id (fully-resolved match ID, e.g. /products/42) from routeId (route definition ID, e.g. /products/$id). If these diverge for dynamic segments, a route would preload correctly but silently miss SSR data injection. Worth adding a test for a dynamic route with ssrRouter match data to confirm both paths use the right key.

Minor

The dev-mode private internals warning fires inside the routerRef.current === null render-phase block. In concurrent rendering, React may run (and abandon) this render before committing, causing the warning to appear even if the component never mounts. A useEffect would tie it to commit.

Follow-up on issuecomment-4189911717:

Addressed in commit 16a781b:

• Added the missing CHANGELOG.md entry for this user-visible Pro bug fix.
• Changed the async router.options.hydrate path so rejected hydration callbacks stop the post-hydration flow instead of continuing into router.load() with partially hydrated client state.
• Added a regression test covering the rejected async hydrate path and verifying the temporary router.ssr flag is still cleared.

Skipped for this PR:

• The O(n×m) lookup in applyDehydratedMatchData remains unchanged because it runs once during hydration and expected match arrays stay small.
• The routeId vs id concern does not apply here; TanStack Router resolves routes by routeId for chunk preloading and keys SSR match dehydration by match.id.
• The dev-only private-internals warning remains in place; I am treating that as a non-blocking architectural preference rather than a correctness blocker for this hydration fix.

Address-review follow-up completed for feedback after the previous summary cutoff at 2026-04-06T01:21:14Z through latest triaged review activity at 2026-04-06T01:24:49Z (default cutoff mode; no check all reviews override).

Mattered

• Addressed: added the missing CHANGELOG.md entry for this user-visible Pro SSR hydration fix.
  • Commit: 16a781bd1
• Addressed: async router.options.hydrate rejections now stop the post-hydration flow instead of continuing into router.load() with partially hydrated client state.
  • Commit: 16a781bd1
  • Regression test added: does not call router.load when async router.options.hydrate rejects
  • Thread replied: discussion_r3037613475
• General review summary issuecomment-4189911717 received a follow-up reply covering the deduplicated must-fix and skipped items.

Skipped

• O(n×m) lookup in applyDehydratedMatchData: left as-is as a non-blocking one-time hydration micro-optimization; rationale replied in discussion_r3037613302.
• routeId vs id dynamic-route concern: reviewer assumption did not match TanStack Router SSR behavior; rationale replied in discussion_r3037613699.
• Dev-only private-internals warning placement: left as-is as a non-blocking architectural preference; rationale included in the general follow-up comment.

No follow-up issue was created in this action chain.

Future full-PR scans should start after this comment unless you explicitly say check all reviews.

Review: Fix TanStack Router SSR Hydration Mismatch

The root cause analysis is correct and well-documented. RouterClient wrapping RouterProvider in <Await>/defer() creates a component tree that differs structurally from the server-rendered tree, which always uses RouterProvider directly — a guaranteed hydration mismatch.

What's good

• Fix is correct. Using RouterProvider directly with synchronous match injection mirrors TanStack Router's own hydrate() in ssr-client.js and eliminates the mismatch.
• StrictMode correctness is carefully handled: didTriggerPostHydrationLoadRef prevents double-load(), didSetSsrFlagRef prevents clobbering user-provided router.ssr, and the finally unconditionally clears the temporary flag so StrictMode unmount/remount doesn't leave it stuck.
• Async hydration callback sequencing (router.options.hydrate → chunk preload → router.load()) with cancellation on unmount is implemented correctly, including aborting router.load() on rejection.
• Good regression tests that fail without the fix (confirmed in the PR description).

Concerns

Private API surface is wide and not version-pinned in package.json

The implementation depends on four internal TanStack Router APIs (matchRoutes, __store.setState, loadRouteChunk, looseRoutesById) that can change without a semver signal. The development warning documents the range (>=1.139.0 <2.0.0) but it is not enforced as a peerDependencies constraint. A minor TanStack Router release reshaping __store would silently break hydration in production (the guard only checks existence, not signature). Consider tightening the peer dep range to ~1.139 or adding a peerDependenciesMeta note.

Silent status override in production

When matchRoutes() returns a match with status: 'pending' that has no corresponding server match, applyDehydratedMatchData overrides it to 'success' silently in production (the warnMissingSsrMatch early-returns). This can mask real data mismatches in production deployments. A lower-severity console.warn (rather than a full dev-only guard) might be worth considering.

children as ReactElement in RouteChunkPreloadGate is a TypeScript lie

children is typed ReactElement | undefined, but the function is declared to return ReactElement and casts children as ReactElement. In practice children is always provided, but TypeScript won't catch a call site omitting it. A narrower return type or an explicit guard would be safer.

O(n·m) match lookup in applyDehydratedMatchData

ssrMatches.find() is called for every client match, resulting in O(n·m) complexity. For typical apps with <20 routes this is negligible, but for large route trees a Map<string, TanStackSsrMatch> keyed by the rehydrated ID would be cleaner and avoids repeated linear scans.

Minor observations

• rehydrateMatchId could be simplified to dehydratedId.replaceAll('\0', '/') (ES2021, already in the TypeScript target range for this package).
• The Suspense fallback: null during chunk preload suspension will render a blank page. A comment or a configurable fallback prop might help consumers who notice the blank flash.
• The backward-compat RouterClient parameter is now a no-op with a one-time deprecation warning — the deprecation path is clear, but a timeline or major-version removal note in the JSDoc would help.

Summary

The fix is sound and the implementation is careful about StrictMode, async sequencing, and cancellation. The main risk is the dependency on TanStack Router internals that could change silently; the other items are relatively low-severity polish.