fix(react-router): render the pending document root only when its beforeLoad context exists

[antur84]

Fixes #8128

Summary

• contextualize (router-core) records __beforeLoadContext when a client beforeLoad settles, mirroring load-server (a void return records {}, so it still counts as settled)
• hydrate() restores __beforeLoadContext from the dehydrated b for committed matches
• Match.tsx's document-root pending exception renders the real component only when the route has no beforeLoad or the match's beforeLoad contribution exists — the condition the branch's own comment ("hydrated matches retain their prior data") already assumes
• New regression test observes the render directly: a dehydrated root with an id skew renders ['undefined', 'en'] without this change, ['en'] with it

Verification

• The new test fails on main and on fix(router-core): keep a reloading match's previous beforeLoad context until it settles #8116's branch (this window opens before contextualize runs, so fix(router-core): keep a reloading match's previous beforeLoad context until it settles #8116 can't close it), passes here
• react-router: 76 files / 1027 tests, type-clean; router-core: 106 files / 1606 tests; solid-router: 62 files / 876 tests (the Match.tsx gate is React-specific); start-client-core: 88/88 runtime tests (its typecheck needs sibling packages not built in my environment, unrelated)
• Production telemetry after shipping an equivalent app-side fallback: the stripped-context window fires ~2–3×/hour in deploy-triggered hydration bursts, mobile-skewed, on our ssr: false shell route

Summary by CodeRabbit

• Bug Fixes

  • Improved SSR hydration when routes use asynchronous loading.
  • Prevented incomplete context from replacing the document root during hydration.
  • Ensured route context is restored consistently before rendering nested content.

• Tests

  • Added regression coverage for hydration scenarios involving asynchronous root loading and server-rendered data.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 84d7dba6-9d25-4b95-b80e-34de3dd67418

📥 Commits

Reviewing files that changed from the base of the PR and between e9f63a6 and fba7a18.

📒 Files selected for processing (3)

• packages/react-router/src/Match.tsx
• packages/react-router/tests/issue-8115-hydration-context-window.test.tsx
• packages/router-core/src/load-client.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The router now stores and restores beforeLoad context during hydration. MatchInner delays retained SSR root rendering when that context is not available. A regression test covers mismatched hydration data and asynchronous root loading.

Changes

Hydration context handling

Layer / File(s)	Summary
Restore beforeLoad context packages/router-core/src/load-client.ts	Client loading stores beforeLoad results on matches. Hydration restores serialized beforeLoad context, using an empty object when no context exists.
Gate SSR root rendering packages/react-router/src/Match.tsx, packages/react-router/tests/issue-8115-hydration-context-window.test.tsx	MatchInner retains SSR output only when required beforeLoad context is available. The regression test verifies that the root receives locale before the index route renders.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to fba7a

This localized hydration fix is merge-ready after normal checks and review; no actionable merge-blocking risk remains.

Possibly related PRs

• TanStack/router#7805: Modifies SSR root rendering and hydration behavior for restored beforeLoad context.
• TanStack/router#8055: Adjusts Match.tsx pending rendering for hydrated SSR document roots.
• TanStack/router#8116: Changes load-client.ts handling of beforeLoad context during hydration.

Suggested labels: package: react-router, package: router-core

Suggested reviewers: sheraff

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the primary change: gating pending document-root rendering on available beforeLoad context.
Linked Issues check	✅ Passed	The changes track and restore beforeLoad context, gate unsafe root rendering, and add a regression test for issue #8128.
Out of Scope Changes check	✅ Passed	All code and test changes directly support hydration context preservation and safe document-root rendering.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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