Skip to content
Source
Sign inSign up
TanStack/router

fix(react-start-client): preserve idle hydration deadlines #8272

OpenLadyBluenotes(GitHub profile, opens in a new tab)wants to merge 8 commits intomain fromfix/react-idle-hydration-deadlineopened

🎯 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

    2. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: react-start-client

    3. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: start-client-core

    4. View your CI Pipeline Execution ↗ for commit eb2cf90887a48c1c2fe553a14f68a02ae447451f

      CommandStatusDurationResult
      nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded8m 7sView ↗
      nx run-many --target=build --exclude=examples/*...✅ Succeeded1m 14sView ↗

      ☁️ Nx Cloud last updated this comment at 2026-10-24 18:53:54 UTC

    5. 🚀 Changeset Version Preview

      2 package(s) bumped directly, 12 bumped as dependents.

      🟩 Patch bumps

      PackageVersionReason
      @tanstack/react-start-client1.168.44 → 1.168.45Changeset
      @tanstack/start-client-core1.170.39 → 1.170.40Changeset
      @tanstack/react-start1.169.4 → 1.169.5Dependent
      @tanstack/react-start-rsc0.1.65 → 0.1.66Dependent
      @tanstack/react-start-server1.167.52 → 1.167.53Dependent
      @tanstack/solid-start1.169.4 → 1.169.5Dependent
      @tanstack/solid-start-client1.168.42 → 1.168.43Dependent
      @tanstack/solid-start-server1.167.50 → 1.167.51Dependent
      @tanstack/start-plugin-core1.171.55 → 1.171.56Dependent
      @tanstack/start-server-core1.169.45 → 1.169.46Dependent
      @tanstack/start-static-server-functions1.167.44 → 1.167.45Dependent
      @tanstack/vue-start1.169.4 → 1.169.5Dependent
      @tanstack/vue-start-client1.167.45 → 1.167.46Dependent
      @tanstack/vue-start-server1.167.50 → 1.167.51Dependent
    6. Review in Change Stack →

      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_commits setting.

      • Last reviewed commit: eb2cf90887a48c1c2fe553a14f68a02ae447451f

      Use the following commands to manage reviews:

      • @coderabbitai resume to resume automatic reviews.
      • @coderabbitai review to 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
      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

      Layer / File(s)Summary
      Idle strategy identity contract
      packages/start-client-core/src/hydration/types.ts, packages/start-client-core/src/hydration/idle.ts
      The 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.tsx
      React 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.md
      Tests cover deadline preservation, timeout changes, custom setup replacement, and unmount cancellation. Documentation and release metadata describe the scheduling behavior.
      Priority: Normal

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

      Change: Bug fix

      Merge Risk: Minimal · up to eb2cf

      The change preserves pending idle hydration and correctly replaces or cancels schedules when required.

      Pre-merge checks: Passed 4 · Failed 1
      Failed Failed checks: 1 warning
      Check nameStatusExplanationResolution
      Docstring CoverageWarningDocstring 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 Passed checks: 4 passed
      Check nameStatusExplanation
      Title checkPassedThe title clearly and concisely describes the main change: preserving idle hydration deadlines in react-start-client.
      Description checkPassedThe 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 checkPassedCheck skipped because no linked issues were found for this pull request.
      Out of Scope Changes checkPassedCheck 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.

      ❤️ Share
      Comment `@coderabbitai help` to get the list of available commands.
    7. Bundle Size Benchmarks

      This pull request does not affect bundle size in any measured scenario.

    8. More templates

      @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@8272

      commit: eb2cf90

    9. Merging 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.

      Learn more about system calls

      See affected benchmarks

      ✅ 194 untouched benchmarks ⏩ 3 skipped benchmarks1


      Comparing fix/react-idle-hydration-deadline (eb2cf90) with main (6b9fe6d) Open in CodSpeed

      Footnotes

      1. 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. ↩

    10. 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 beforeEach hook 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. The child.tsx route involved in the failure does not use <Hydrate> or idle() at all, so our hydration lifecycle changes could not have caused this.

      No code changes were suggested for this issue.

      Trigger a rerun:

      Rerun CI

      Nx Cloud 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)
    11. 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.

      Nx Cloud 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)
    12. 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.

      Nx Cloud 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)
    13. 🦋 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
      NameType
      @tanstack/react-start-clientPatch
      @tanstack/start-client-corePatch
      @tanstack/react-startPatch
      @tanstack/react-start-rscPatch
      @tanstack/solid-start-clientPatch
      @tanstack/solid-startPatch
      @tanstack/start-server-corePatch
      @tanstack/start-static-server-functionsPatch
      @tanstack/vue-start-clientPatch
      @tanstack/vue-startPatch
      @tanstack/react-start-serverPatch
      @tanstack/solid-start-serverPatch
      @tanstack/start-plugin-corePatch
      @tanstack/vue-start-serverPatch

      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.