fix(react-start-client): preserve idle hydration deadlines #8272
main fromfix/react-idle-hydration-deadline·opened 🎯 Changes#
Inline idle() calls create new strategy objects on each render, which restarted pending hydration. Keep the existing schedule when its timeout is unchanged, while preserving timeout and strategy changes, custom setup overrides, and unmount cleanup.
✅ Checklist#
- I have followed the steps in the Contributing guide.
- I have tested code changes locally with the relevant test commands, or tests do not apply to this pull request.
- I fully understand the code in this pull request, including any code generated with AI assistance.
🚀 Release Impact#
- This change affects published code, and I have generated a changeset.
- This change is docs/CI/dev-only (no release).
Summary by CodeRabbit#
Bug Fixes
- Improved idle hydration reliability during parent component re-renders.
- Pending hydration stays scheduled when the idle timeout is unchanged.
- Hydration is rescheduled when the timeout or strategy changes.
- Pending idle hydration is cancelled when a component is unmounted.
- Custom setup functions that replace an idle strategy take effect as expected.
Documentation
- Clarified how recreating idle hydration settings affects scheduling and replacement behavior.
- 1
github-actions[bot](GitHub profile, opens in a new tab) added labelsdocumentation
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: react-start-client
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: start-client-core
🚀 Changeset Version Preview#
2 package(s) bumped directly, 12 bumped as dependents.
🟩 Patch bumps#
Package Version Reason @tanstack/react-start-client1.168.44 → 1.168.45 Changeset @tanstack/start-client-core1.170.39 → 1.170.40 Changeset @tanstack/react-start1.169.4 → 1.169.5 Dependent @tanstack/react-start-rsc0.1.65 → 0.1.66 Dependent @tanstack/react-start-server1.167.52 → 1.167.53 Dependent @tanstack/solid-start1.169.4 → 1.169.5 Dependent @tanstack/solid-start-client1.168.42 → 1.168.43 Dependent @tanstack/solid-start-server1.167.50 → 1.167.51 Dependent @tanstack/start-plugin-core1.171.55 → 1.171.56 Dependent @tanstack/start-server-core1.169.45 → 1.169.46 Dependent @tanstack/start-static-server-functions1.167.44 → 1.167.45 Dependent @tanstack/vue-start1.169.4 → 1.169.5 Dependent @tanstack/vue-start-client1.167.45 → 1.167.46 Dependent @tanstack/vue-start-server1.167.50 → 1.167.51 Dependent Note
Reviews paused#
It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the
reviews.auto_review.auto_pause_after_reviewed_commitssetting.- Last reviewed commit: eb2cf90887a48c1c2fe553a14f68a02ae447451f
Use the following commands to manage reviews:
@coderabbitai resumeto resume automatic reviews.@coderabbitai reviewto trigger a single review.
Use the checkboxes below for quick actions:
- ▶️ Resume reviews
- 🔍 Trigger review
No actionable comments were generated in the recent review.
Recent review info-
Run configuration-
- Source mode: Auto
- Repository: TanStack/router
- Branch: fix/react-idle-hydration-deadline
- File: .coderabbit.yaml
- Commit: eb2cf90
- Layers: Repository YAML
- Review profile: CHILL
- Plan: Advanced
- Run ID:
0fedc939-478d-47b8-a78f-2f3e7a1582c0
Commits-
Reviewing files that changed from the base of the PR and between 1e5fe235a98c1f5925743c82affae8221619a1d2 and eb2cf90887a48c1c2fe553a14f68a02ae447451f.
Files selected for processing: 1-
docs/start/framework/react/guide/deferred-hydration.md
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 3 remain after this review.
-
Walkthrough
-
Idle hydration preserves pending work across parent rerenders when its timeout remains unchanged. It reschedules when the timeout or strategy changes and cancels pending work on unmount. Tests, documentation, and a changeset cover these behaviors.
Changes: Idle hydration scheduling
Priority:Layer / File(s) Summary Idle strategy identity contract
packages/start-client-core/src/hydration/types.ts,packages/start-client-core/src/hydration/idle.tsThe idle setup function exposes its normalized timeout through _i. The hydration strategy type supports this optional property.React hydration scheduling integration
packages/react-start-client/src/GenericHydrate.tsxReact hydration stores the latest strategy and uses a stable strategy key and strategy type to control effect execution. Scheduling behavior validation and documentation
packages/react-start-client/src/tests/Hydrate.test.tsx,docs/start/framework/react/guide/deferred-hydration.md,.changeset/idle-hydration-deadline.mdTests cover deadline preservation, timeout changes, custom setup replacement, and unmount cancellation. Documentation and release metadata describe the scheduling behavior. NormalEstimated code review effort: 3 (Moderate) | ~20 minutes
Change: Bug fix
Merge Risk:
Minimal · up toeb2cf-
The change preserves pending idle hydration and correctly replaces or cancels schedules when required.
Pre-merge checks:
4 · 1-
Failed checks: 1 warningCheck name Status Explanation Resolution Docstring Coverage Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 4 files. (1 skipped: 1 … Write docstrings for the functions missing them to satisfy the coverage threshold. Passed checks: 4 passed-
Check name Status Explanation Title check The title clearly and concisely describes the main change: preserving idle hydration deadlines in react-start-client. Description check The description includes all required template sections, explains the motivation and behavior changes, confirms testing and contribution requirements, and records the changeset for published code. Linked Issues check Check skipped because no linked issues were found for this pull request. Out of Scope Changes check Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage
-
Explanation
Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 4 files. (1 skipped: 1 unsupported.)
Resolution
Write docstrings for the functions missing them to satisfy the coverage threshold.
-
Finishing Touches
-
🧪 Generate unit tests (beta)
-
- Commit to this branch
- 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.
Comment `@coderabbitai help` to get the list of available commands.Bundle Size Benchmarks#
This pull request does not affect bundle size in any measured scenario.
More templates
- tanstack-router-react-example-authenticated-routes
- tanstack-router-react-example-authenticated-routes-firebase
- tanstack-router-react-example-basic
- tanstack-router-react-example-basic-default-search-params
- tanstack-router-react-example-basic-devtools-panel
- tanstack-router-react-example-basic-file-based
- tanstack-router-react-example-basic-non-nested-devtools
- tanstack-router-react-example-react-query
- tanstack-router-react-example-basic-react-query-file-based
- tanstack-router-react-example-basic-ssr-file-based
- tanstack-router-react-example-basic-ssr-streaming-file-based
- tanstack-router-react-example-basic-virtual-file-based
- tanstack-router-react-example-basic-virtual-inside-file-based
- tanstack-router-react-example-deferred-data
- tanstack-router-i18n-paraglide
- tanstack-router-react-example-kitchen-sink
- tanstack-router-react-example-kitchen-sink-file-based
- tanstack-router-react-example-kitchen-sink-react-query
- tanstack-router-react-example-kitchen-sink-react-query-file-based
- tanstack-router-react-example-large-file-based
- tanstack-router-react-example-location-masking
- tanstack-router-react-example-navigation-blocking
- tanstack-router-react-example-quickstart
- tanstack-router-react-example-quickstart-esbuild-file-based
- tanstack-router-react-example-quickstart-file-based
- tanstack-router-react-example-quickstart-rspack-file-based
- tanstack-router-react-example-quickstart-webpack-file-based
- router-monorepo-react-query
- router-mono-simple
- router-mono-simple-lazy
- tanstack-router-react-example-scroll-restoration
- tanstack-search-validator-adapters
- tanstack-start-example-bare
- tanstack-start-example-basic
- tanstack-start-example-basic-auth
- tanstack-router-react-example-basic-authjs
- tanstack-start-example-basic-cloudflare
- tanstack-start-example-basic-react-query
- tanstack-start-example-basic-rsbuild
- tanstack-start-example-basic-static
- tanstack-start-bun-hosting
- tanstack-start-example-clerk-basic
- tanstack-start-example-convex-trellaux
- tanstack-start-example-counter
- tanstack-start-i18n-paraglide
- tanstack-start-example-large
- tanstack-start-example-material-ui
- tanstack-start-example-next-migration
- tanstack-start-example-rscs
- tanstack-start-streaming-data-from-server-functions
- tanstack-start-example-supabase-basic
- tanstack-start-tailwind-v4
- tanstack-start-example-trellaux
- tanstack-start-example-workos
- tanstack-router-react-example-view-transitions
- tanstack-router-react-example-with-framer-motion
- tanstack-router-react-example-with-trpc
- tanstack-router-react-example-with-trpc-react-query
- tanstack-router-solid-example-authenticated-routes
- tanstack-router-solid-example-authenticated-routes-firebase
- tanstack-router-solid-example-basic
- tanstack-router-solid-example-basic-default-search-params
- tanstack-router-solid-example-basic-devtools-panel
- tanstack-router-solid-example-basic-file-based
- tanstack-router-solid-example-basic-non-nested-devtools
- tanstack-router-solid-example-basic-solid-query
- tanstack-router-solid-example-basic-solid-query-file-based
- tanstack-router-solid-example-basic-ssr-file-based
- tanstack-router-solid-example-basic-ssr-streaming-file-based
- tanstack-router-solid-example-basic-virtual-file-based
- tanstack-router-solid-example-basic-virtual-inside-file-based
- tanstack-router-solid-example-deferred-data
- tanstack-router-solid-i18n-paraglide
- tanstack-router-solid-example-kitchen-sink
- tanstack-router-solid-example-kitchen-sink-file-based
- tanstack-router-solid-example-kitchen-sink-solid-query
- tanstack-router-solid-example-kitchen-sink-solid-query-file-based
- tanstack-router-solid-example-large-file-based
- tanstack-router-solid-example-location-masking
- tanstack-router-solid-example-navigation-blocking
- tanstack-router-solid-example-quickstart
- tanstack-router-solid-example-quickstart-esbuild-file-based
- tanstack-router-solid-example-quickstart-file-based
- tanstack-router-solid-example-quickstart-rspack-file-based
- tanstack-router-solid-example-quickstart-webpack-file-based
- @tanstack/router-solid-mono-simple
- router-solid-mono-simple-lazy
- router-solid-monorepo-solid-query
- tanstack-router-solid-example-scroll-restoration
- tanstack-solid-router-search-validator-adapters
- tanstack-solid-start-example-basic
- tanstack-solid-start-example-basic-auth
- tanstack-solid-start-example-basic-authjs
- tanstack-solid-start-example-basic-cloudflare
- tanstack-solid-start-example-basic-netlify
- tanstack-solid-start-example-basic-nitro
- tanstack-start-example-basic-solid-query
- tanstack-solid-start-example-basic-static
- tanstack-solid-start-bun-hosting
- tanstack-solid-start-example-convex-better-auth
- tanstack-solid-start-example-counter
- tanstack-solid-start-i18n-paraglide
- tanstack-solid-start-example-large
- tanstack-solid-start-streaming-data-from-server-functions
- tanstack-solid-start-example-supabase-basic
- tanstack-solid-start-tailwind-v4
- tanstack-router-solid-example-view-transitions
- tanstack-router-solid-example-with-framer-motion
- tanstack-router-solid-example-with-trpc
- tanstack-router-vue-example-basic-jsx
- tanstack-router-vue-example-basic-file-based-jsx
- tanstack-router-vue-example-basic-file-based-sfc
@tanstack/arktype-adapter
npm i https://pkg.pr.new/@tanstack/arktype-adapter@8272@tanstack/eslint-plugin-router
npm i https://pkg.pr.new/@tanstack/eslint-plugin-router@8272@tanstack/eslint-plugin-start
npm i https://pkg.pr.new/@tanstack/eslint-plugin-start@8272@tanstack/history
npm i https://pkg.pr.new/@tanstack/history@8272@tanstack/react-router
npm i https://pkg.pr.new/@tanstack/react-router@8272@tanstack/react-router-devtools
npm i https://pkg.pr.new/@tanstack/react-router-devtools@8272@tanstack/react-router-ssr-query
npm i https://pkg.pr.new/@tanstack/react-router-ssr-query@8272@tanstack/react-start
npm i https://pkg.pr.new/@tanstack/react-start@8272@tanstack/react-start-client
npm i https://pkg.pr.new/@tanstack/react-start-client@8272@tanstack/react-start-rsc
npm i https://pkg.pr.new/@tanstack/react-start-rsc@8272@tanstack/react-start-server
npm i https://pkg.pr.new/@tanstack/react-start-server@8272@tanstack/router-cli
npm i https://pkg.pr.new/@tanstack/router-cli@8272@tanstack/router-core
npm i https://pkg.pr.new/@tanstack/router-core@8272@tanstack/router-devtools
npm i https://pkg.pr.new/@tanstack/router-devtools@8272@tanstack/router-devtools-core
npm i https://pkg.pr.new/@tanstack/router-devtools-core@8272@tanstack/router-generator
npm i https://pkg.pr.new/@tanstack/router-generator@8272@tanstack/router-plugin
npm i https://pkg.pr.new/@tanstack/router-plugin@8272@tanstack/router-ssr-query-core
npm i https://pkg.pr.new/@tanstack/router-ssr-query-core@8272@tanstack/router-utils
npm i https://pkg.pr.new/@tanstack/router-utils@8272@tanstack/router-vite-plugin
npm i https://pkg.pr.new/@tanstack/router-vite-plugin@8272@tanstack/solid-router
npm i https://pkg.pr.new/@tanstack/solid-router@8272@tanstack/solid-router-devtools
npm i https://pkg.pr.new/@tanstack/solid-router-devtools@8272@tanstack/solid-router-ssr-query
npm i https://pkg.pr.new/@tanstack/solid-router-ssr-query@8272@tanstack/solid-start
npm i https://pkg.pr.new/@tanstack/solid-start@8272@tanstack/solid-start-client
npm i https://pkg.pr.new/@tanstack/solid-start-client@8272@tanstack/solid-start-server
npm i https://pkg.pr.new/@tanstack/solid-start-server@8272@tanstack/start-client-core
npm i https://pkg.pr.new/@tanstack/start-client-core@8272@tanstack/start-fn-stubs
npm i https://pkg.pr.new/@tanstack/start-fn-stubs@8272@tanstack/start-plugin-core
npm i https://pkg.pr.new/@tanstack/start-plugin-core@8272@tanstack/start-server-core
npm i https://pkg.pr.new/@tanstack/start-server-core@8272@tanstack/start-static-server-functions
npm i https://pkg.pr.new/@tanstack/start-static-server-functions@8272@tanstack/start-storage-context
npm i https://pkg.pr.new/@tanstack/start-storage-context@8272@tanstack/valibot-adapter
npm i https://pkg.pr.new/@tanstack/valibot-adapter@8272@tanstack/virtual-file-routes
npm i https://pkg.pr.new/@tanstack/virtual-file-routes@8272@tanstack/vue-router
npm i https://pkg.pr.new/@tanstack/vue-router@8272@tanstack/vue-router-devtools
npm i https://pkg.pr.new/@tanstack/vue-router-devtools@8272@tanstack/vue-router-ssr-query
npm i https://pkg.pr.new/@tanstack/vue-router-ssr-query@8272@tanstack/vue-start
npm i https://pkg.pr.new/@tanstack/vue-start@8272@tanstack/vue-start-client
npm i https://pkg.pr.new/@tanstack/vue-start-client@8272@tanstack/vue-start-server
npm i https://pkg.pr.new/@tanstack/vue-start-server@8272@tanstack/zod-adapter
npm i https://pkg.pr.new/@tanstack/zod-adapter@8272commit:
eb2cf90Merging this PR will not alter performance#
1 warning
:warning: 46 benchmarks are dominated by system calls
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.
✅ 194untouched benchmarks⏩ 3skipped benchmarks1
Comparingfix/react-idle-hydration-deadline(eb2cf90) withmain(6b9fe6d)Footnotes#
-
3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩
-
Important
At least one additional CI pipeline execution has run since the conclusion below was written and it may no longer be applicable.
Nx Cloud has identified a possible root cause for your failed CI:#
We classified this failure as an environment issue rather than a code regression. The failing
beforeEachhook exhausted its 20-second retry window waiting for rsbuild to reflect a restored route file — a timing sensitivity in the CI environment unrelated to the idle hydration changes in this PR. Thechild.tsxroute involved in the failure does not use<Hydrate>oridle()at all, so our hydration lifecycle changes could not have caused this.No code changes were suggested for this issue.
Trigger a rerun:
View detailed reasoning on Nx Cloud ↗
🎓 Learn more about Self-Healing CI on [nx.dev](https://nx.dev/docs/features/ci-features/self-healing-ci?utm_source=pull-request&utm_medium=comment)Nx Cloud has identified a flaky task in your failed CI:#
🔂 Since the failure was identified as flaky, we triggered a CI rerun by adding an empty commit to this branch.
View detailed reasoning in Nx Cloud ↗
🎓 Learn more about Self-Healing CI on [nx.dev](https://nx.dev/docs/features/ci-features/self-healing-ci?utm_source=pull-request&utm_medium=comment)Nx Cloud has identified a flaky task in your failed CI:#
🔂 Since the failure was identified as flaky, we triggered a CI rerun by adding an empty commit to this branch.
View detailed reasoning in Nx Cloud ↗
🎓 Learn more about Self-Healing CI on [nx.dev](https://nx.dev/docs/features/ci-features/self-healing-ci?utm_source=pull-request&utm_medium=comment)🦋 Changeset detected#
Latest commit: eb2cf90887a48c1c2fe553a14f68a02ae447451f
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 14 packages
Name Type @tanstack/react-start-client Patch @tanstack/start-client-core Patch @tanstack/react-start Patch @tanstack/react-start-rsc Patch @tanstack/solid-start-client Patch @tanstack/solid-start Patch @tanstack/start-server-core Patch @tanstack/start-static-server-functions Patch @tanstack/vue-start-client Patch @tanstack/vue-start Patch @tanstack/react-start-server Patch @tanstack/solid-start-server Patch @tanstack/start-plugin-core Patch @tanstack/vue-start-server Patch Not sure what this means? Click here to learn what changesets are.
Click here if you're a maintainer who wants to add another changeset to this PR
Sign in to join this conversation.
View your CI Pipeline Execution ↗ for commit eb2cf90887a48c1c2fe553a14f68a02ae447451f
nx affected --targets=test:eslint,test:unit,tes...nx run-many --target=build --exclude=examples/*...☁️ Nx Cloud last updated this comment at
2026-10-24 18:53:54UTC