You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
fix(react-start-client): call HydrationBoundary hooks before the visible() gate - #8653
Fixes#8652. The fix and its root-cause analysis come from this PR's original commit (9b225fd). A maintainer took the PR over to align it with the compiler rewrite (#8817), which carries the same fix.
The bug
<Hydrate when={visible()}> renders HydrationBoundary, which suspends on its gate with if (!g.r) use(g.p) and called useEffect only after that check. React replays a component that suspended in use with its re-render dispatcher, and only use switches away from it. When the intersection arrives while React waits to replay, g.r is already true, so the replay skips use and reaches a hook the first attempt never called. React throws "Update hook called on initial render" (#467 in production). During hydration React then drops the boundary's server HTML and client-renders it: the fallback replaces the markup until the split code loads, and onRecoverableError reports the error.
The fix
packages/react-start-client/src/hydration/visible.tsx: the effect moves above the gate, so every attempt calls the same hooks. Effects run only after commit, so onHydrated still fires once, after the boundary renders its children.
The component destructures only o and reads props.g inline. Keeping const { g, o } = props after the reorder costs +6 B gzip on react-start.deferred-hydration. The file is now identical to #8817's.
The test
src/tests/Hydrate.test.tsx, "hydrates a visible boundary whichever task the intersection arrives in": it server-renders a visible() boundary, hydrates that HTML with hydrateRoot, and fires the intersection in each of the 12 tasks around the first hydration attempt. It asserts that every run hydrates (onHydrated resolves) with no recoverable error. It fails on main (the error appears when the intersection lands one task in) and passes with the fix.
This test replaces the earlier src/tests/visible.test.tsx, which also failed on main. That test triggered the replay from a client-only createRoot render through a side effect during render. The hydration test covers the case users hit (server HTML being dropped), doesn't depend on one scheduling trick, and is the same test #8817 has. Keeping both would test the same thing twice.
The changeset is renamed to .changeset/visible-hydrate-replay.md, with #8817's wording (patch).
E2E: tanstack-react-start-e2e-deferred-hydration (16 tests, dev and prod) and tanstack-react-start-e2e-rsc-deferred-hydration (3 tests, dev and prod) pass.
Bundle size (client, against main at ad5b3b7a09)
Scenario
gzip
raw
brotli
react-start.deferred-hydration
+0 B
+2 B
+7 B
the other 17 scenarios
0
0
0
The original shape (const { g, o } = props after the reorder) measured +6 B gzip, +0 raw and −8 B brotli on react-start.deferred-hydration. These are the same numbers #8817 reports for its visible() fix.
The three files here are byte-identical to #8817's (visible.tsx, the Hydrate.test.tsx test, the changeset). A test merge of this branch into main followed by #8817's head adds no conflicts: #8817's conflict set with main stays the same 19 unrelated files. After this lands, #8817 only needs to drop the visible() bundle-size note from its description.
No actionable comments were generated in the recent review.
Walkthrough
HydrationBoundary now declares its onHydrated effect before checking or suspending on the visibility gate. A regression test exercises delayed intersections during hydration and checks for recoverable errors. A patch changeset records the fix.
Changes: Visible hydration boundary
Layer / File(s)
Summary
Hook order and replay regression test packages/react-start-client/src/hydration/visible.tsx, packages/react-start-client/src/tests/Hydrate.test.tsx, .changeset/visible-hydrate-replay.md
HydrationBoundary declares the onHydrated effect before the gate check and suspension path. The test checks hydration with intersections after 0 through 11 task delays and expects no recoverable errors. The changeset records a patch release for @tanstack/react-start-client.
TanStack/router#8778 — The issue concerns the closed gate in a deferred Hydrate boundary. This change moves the effect before the gate check but does not change the gate suspension behavior.
Suggested labels:package: react-start-client
Suggested reviewers:schiller-manuel
Merge Risk: Minimal · up to 47b38
The visibility-hydration fix has a regression test that completes hydration before checking for errors. No actionable merge-blocking issue remains.
Pre-merge checks: 5
Check name
Status
Explanation
Title check
The title clearly identifies the primary fix: moving HydrationBoundary hooks before the visible() gate.
Description check
The description includes the required Changes, Checklist, and Release Impact sections. It explains the bug, fix, tests, validation results, release impact, and AI assistance disclosure.
Linked Issues check
The PR addresses the only active directly linked issue, #8652. The reviewed head moves the React.useEffect call in HydrationBoundary (packages/react-start-client/src/hydration/visible.tsx) above…
Out of Scope Changes check
The whole-PR diff against the merge base contains three changed files, and each supports #8652. visible.tsx contains only the hook-order change that fixes the reported #467 replay. `Hydrate.test.tsx…
Docstring Coverage
Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
Full details: Linked Issues check
Explanation
The PR addresses the only active directly linked issue, #8652. The reviewed head moves the React.useEffect call in HydrationBoundary (packages/react-start-client/src/hydration/visible.tsx) above the if (!props.g.r) gate and reactUse(props.g.p) call. Every render attempt now calls the same hooks in the same order, so a replay after use suspended cannot reach a hook the first attempt did not call. This is the fix the issue proposes. onHydrated still runs from the effect after commit, so it fires once after the children render.
The regression test moved from visible.test.tsx (removed at this head) to packages/react-start-client/src/tests/Hydrate.test.tsx, test "hydrates a visible boundary whichever task the intersection arrives in". It server-renders a visible() boundary, hydrates it with hydrateRoot, fires the intersection after 0 to 11 task delays, and asserts that every run calls onHydrated with no onRecoverableError errors. No recoverable error means React did not discard the server HTML (#422 path). The issue's stated expected behavior (no #467 during hydration, server HTML kept until hydration) is covered by this automated test.
The issue's original reproducer used a client-only createRoot mount path. The new test covers hydration only. The issue's expectation of no throw on mount is addressed by the same hook-order fix, but no test in this head exercises the mount-only path. This gap does not block the verdict because the issue's reproducer is an external fork link, and the hydration test covers the user-facing failure.
Full details: Out of Scope Changes check
Explanation
The whole-PR diff against the merge base contains three changed files, and each supports #8652. visible.tsx contains only the hook-order change that fixes the reported #467 replay. Hydrate.test.tsx adds the visible import and the regression test for that replay. The changeset (.changeset/visible-hydrate-replay.md, patch release for @tanstack/react-start-client) records the published fix. The earlier visible.test.tsx no longer exists at this head, so it cannot add out-of-scope changes. No unrelated change is demonstrated.
Full details: Docstring Coverage
Explanation
Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 1 functions across 2 files. (1 skipped: 1 unsupported.)
Finishing Touches
Generate unit tests (beta)
Create a new PR
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
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.
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.
…nd test it through hydration
- Destructure only `o` and read `props.g` inline: keeps the deferred-hydration
client gzip at main's (+6 B with both destructured after the reorder).
- Replace the client-render test with a hydration test that runs the
intersection in each task around the boundary's first hydration attempt and
asserts no recoverable error. It fails on main.
- Use the changeset wording of TanStack#8817.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.
⚠️1 benchmark with a significant change ran on different hardware
Its base and head results were measured on machines with a different CPU, core count or memory, so the change might not come from the code. Run base and head on the same runner type.
#8817's side for the split-out PRs:
- #8861 (Start router options): the PR's generator-config, Vite and
Rsbuild wiring; main's start-router-wiring test and start-app helper
dropped (start-build-options, start-dev-route-tree-footer and
start-compose-project-path test the same four behaviours). Main's
changeset kept; the duplicated bullets leave start-compiler-yuku.md.
- #8860 (split route source maps): the PR's own loader; compilers.ts stays
deleted; main's source-maps test dropped (build-source-maps and
dev-source-maps test webpack, Rspack and Vite dev). unplugin ^3.5.0 kept
from main (no downgrade). Main's changeset kept; the PR's source map
clause leaves router-plugin-yuku.md.
- #8653 (visible() hooks): merged to the PR's file, test and changeset
unchanged.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🎯 Changes
Fixes #8652. The fix and its root-cause analysis come from this PR's original commit (9b225fd). A maintainer took the PR over to align it with the compiler rewrite (#8817), which carries the same fix.
The bug
<Hydrate when={visible()}>rendersHydrationBoundary, which suspends on its gate withif (!g.r) use(g.p)and calleduseEffectonly after that check. React replays a component that suspended inusewith its re-render dispatcher, and onlyuseswitches away from it. When the intersection arrives while React waits to replay,g.ris already true, so the replay skipsuseand reaches a hook the first attempt never called. React throws "Update hook called on initial render" (#467 in production). During hydration React then drops the boundary's server HTML and client-renders it: the fallback replaces the markup until the split code loads, andonRecoverableErrorreports the error.The fix
packages/react-start-client/src/hydration/visible.tsx: the effect moves above the gate, so every attempt calls the same hooks. Effects run only after commit, soonHydratedstill fires once, after the boundary renders its children.The component destructures only
oand readsprops.ginline. Keepingconst { g, o } = propsafter the reorder costs +6 B gzip onreact-start.deferred-hydration. The file is now identical to #8817's.The test
src/tests/Hydrate.test.tsx, "hydrates a visible boundary whichever task the intersection arrives in": it server-renders avisible()boundary, hydrates that HTML withhydrateRoot, and fires the intersection in each of the 12 tasks around the first hydration attempt. It asserts that every run hydrates (onHydratedresolves) with no recoverable error. It fails onmain(the error appears when the intersection lands one task in) and passes with the fix.This test replaces the earlier
src/tests/visible.test.tsx, which also failed onmain. That test triggered the replay from a client-onlycreateRootrender through a side effect during render. The hydration test covers the case users hit (server HTML being dropped), doesn't depend on one scheduling trick, and is the same test #8817 has. Keeping both would test the same thing twice.The changeset is renamed to
.changeset/visible-hydrate-replay.md, with #8817's wording (patch).Validation
@tanstack/react-start-client:test:unit,test:types,test:eslint,test:buildpass.tanstack-react-start-e2e-deferred-hydration(16 tests, dev and prod) andtanstack-react-start-e2e-rsc-deferred-hydration(3 tests, dev and prod) pass.Bundle size (client, against
mainatad5b3b7a09)react-start.deferred-hydrationThe original shape (
const { g, o } = propsafter the reorder) measured +6 B gzip, +0 raw and −8 B brotli onreact-start.deferred-hydration. These are the same numbers #8817 reports for itsvisible()fix.Relation to #8817
The three files here are byte-identical to #8817's (
visible.tsx, theHydrate.test.tsxtest, the changeset). A test merge of this branch intomainfollowed by #8817's head adds no conflicts: #8817's conflict set withmainstays the same 19 unrelated files. After this lands, #8817 only needs to drop thevisible()bundle-size note from its description.✅ Checklist
🚀 Release Impact
🤖 Generated with Claude Code
Summary by CodeRabbit