Skip to content
Source
Sign inSign up
TanStack/router

fix(start): release cancelled hydration replay events #8268

OpenLadyBluenotes(GitHub profile, opens in a new tab)wants to merge 8 commits intomain fromfix/start-hydration-replay-cleanupopened

🎯 Changes

Queued interaction events keep removed DOM nodes alive when a deferred hydration boundary unmounts before hydration completes. Clear those queues when the final gate consumer is released in React and Solid, including nested markers whose gates have not mounted yet. Successful hydration still replays queued events.

✅ 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

    • Fixed deferred hydration interactions so queued events are released correctly when boundaries are hidden or unmounted.
    • Prevented stale interactions from replaying after a boundary is removed.
    • Ensured shared and nested hydration boundaries retain or clear queued interactions appropriately.
  • Tests

    • Expanded React and Solid end-to-end coverage for aborted and unmounted deferred hydration boundaries.
    • Added coverage for interaction replay and cleanup scenarios.
    • Improved navigation and shared widget styling verification.
    1. Review Change StackReview 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: 3090b12ca694bd0af7d2ba9a0979144b69743315
      • Latest commit, not reviewed: feb19063a95051f807182d0506b32d1bfd56f1e2

      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

      Configuration used: Path: .coderabbit.yaml

      Review profile: CHILL

      Plan: Advanced

      Run ID: af689716-e502-4297-8289-0423746132ca

      📥 Commits

      Reviewing files that changed from the base of the PR and between f600d91caa023022b058a8130fd95d95b9c97822 and 3090b12ca694bd0af7d2ba9a0979144b69743315.

      📒 Files selected for processing (1)
      • packages/start-client-core/src/hydration/runtime.ts
      🚧 Files skipped from review as they are similar to previous changes (1)
      • packages/start-client-core/src/hydration/runtime.ts

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

      Walkthrough

      Deferred hydration gate release now clears queued interaction replay events for released gates and nested hydration markers. React and Solid cleanup pass marker elements to the runtime. Unit and end-to-end tests cover replay, abort, and navigation behavior.

      Changes: Deferred hydration replay cleanup

      Layer / File(s)Summary
      Replay queue lifecycle
      packages/start-client-core/src/hydration/replay.ts, packages/start-client-core/src/hydration/interaction.ts, packages/start-client-core/src/hydration/runtime.ts
      Defines a shared replay-event map and clears events for released gates and nested hydration markers.
      Client cleanup wiring
      packages/react-start-client/src/GenericHydrate.tsx, packages/solid-start-client/src/GenericHydrate.tsx
      Passes marker elements to releaseGate during hydration cleanup.
      Replay cleanup validation
      packages/start-client-core/tests/hydration-interaction.test.ts, e2e/react-start/deferred-hydration/tests/hydration.spec.ts, e2e/solid-start/deferred-hydration/tests/hydration.spec.ts, e2e/solid-start/start-manifest/tests/start-manifest.spec.ts, .changeset/fair-dryers-think.md
      Tests replay cleanup, shared and replacement gates, nested markers, unhydrated abort behavior, route navigation, CSS assertions, and patch release declarations.
      Priority: Normal

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

      Change: Bug fix

      Merge Risk: Minimal · up to 3090b

      No actionable merge-blocking risk remains from the reviewed change.

      🚥 Pre-merge checks | ✅ 4 | ❌ 1

      ❌ Failed checks (1 warning)

      Check nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring coverage is 9.09% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 9 files.Write docstrings for the functions missing them to satisfy the coverage threshold.
      ✅ Passed checks (4 passed)
      Check nameStatusExplanation
      Title check✅ PassedThe title clearly and concisely describes the main change: releasing cancelled hydration replay events.
      Description check✅ PassedThe description includes the required Changes, Checklist, and Release Impact sections. It explains the motivation, confirms testing and review, and identifies the generated changeset.
      Linked Issues check✅ PassedCheck skipped because no linked issues were found for this pull request.
      Out of Scope Changes check✅ PassedCheck skipped because no linked issues were found for this pull request.
      ✨ Finishing Touches: 💡 1
      📝 Generate docstrings: 💡
      • Create stacked PR
      • Commit on current branch
      🧪 Generate unit tests (beta)
      • Create PR with unit tests
      • Commit unit tests in branch `fix/start-hydration-replay-cleanup`
      • 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.
    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: solid-start-client

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

    5. View your CI Pipeline Execution ↗ for commit feb19063a95051f807182d0506b32d1bfd56f1e2

      CommandStatusDurationResult
      nx run-many --target=build --exclude=examples/*...✅ Succeeded1m 46sView ↗

      ☁️ Nx Cloud last updated this comment at 2026-10-24 22:01:05 UTC

    6. 🚀 Changeset Version Preview

      3 package(s) bumped directly, 11 bumped as dependents.

      🟩 Patch bumps

      PackageVersionReason
      @tanstack/react-start-client1.168.44 → 1.168.45Changeset
      @tanstack/solid-start-client1.168.42 → 1.168.43Changeset
      @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-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
    7. Bundle Size Benchmarks

      • Commit: 6b5ac8bb5741
      • Measured at: 2026-10-24T21:57:35.044Z
      • Baseline source: history:6b9fe6d29552
      • Dashboard: bundle-size history

      The following scenarios have bundle-size changes compared with the baseline:

      ScenarioCurrent (gzip)Initial (gzip)RawBrotliTrend
      solid-start.deferred-hydration49.2 KiB
      +26 B
      46.1 KiB
      -2 B
      142.4 KiB
      +62 B
      43.9 KiB
      +19 B
      ▁▁▁▁▁▁▁▁▁▁▁█

      Current gzip tracks all emitted client JS chunks. Initial gzip tracks only the entry/import graph. Trend sparkline is historical current gzip ending with this PR measurement; lower is better.

    8. More templates

      @tanstack/arktype-adapter

      npm i https://pkg.pr.new/@tanstack/arktype-adapter@8268

      @tanstack/eslint-plugin-router

      npm i https://pkg.pr.new/@tanstack/eslint-plugin-router@8268

      @tanstack/eslint-plugin-start

      npm i https://pkg.pr.new/@tanstack/eslint-plugin-start@8268

      @tanstack/history

      npm i https://pkg.pr.new/@tanstack/history@8268

      @tanstack/react-router

      npm i https://pkg.pr.new/@tanstack/react-router@8268

      @tanstack/react-router-devtools

      npm i https://pkg.pr.new/@tanstack/react-router-devtools@8268

      @tanstack/react-router-ssr-query

      npm i https://pkg.pr.new/@tanstack/react-router-ssr-query@8268

      @tanstack/react-start

      npm i https://pkg.pr.new/@tanstack/react-start@8268

      @tanstack/react-start-client

      npm i https://pkg.pr.new/@tanstack/react-start-client@8268

      @tanstack/react-start-rsc

      npm i https://pkg.pr.new/@tanstack/react-start-rsc@8268

      @tanstack/react-start-server

      npm i https://pkg.pr.new/@tanstack/react-start-server@8268

      @tanstack/router-cli

      npm i https://pkg.pr.new/@tanstack/router-cli@8268

      @tanstack/router-core

      npm i https://pkg.pr.new/@tanstack/router-core@8268

      @tanstack/router-devtools

      npm i https://pkg.pr.new/@tanstack/router-devtools@8268

      @tanstack/router-devtools-core

      npm i https://pkg.pr.new/@tanstack/router-devtools-core@8268

      @tanstack/router-generator

      npm i https://pkg.pr.new/@tanstack/router-generator@8268

      @tanstack/router-plugin

      npm i https://pkg.pr.new/@tanstack/router-plugin@8268

      @tanstack/router-ssr-query-core

      npm i https://pkg.pr.new/@tanstack/router-ssr-query-core@8268

      @tanstack/router-utils

      npm i https://pkg.pr.new/@tanstack/router-utils@8268

      @tanstack/router-vite-plugin

      npm i https://pkg.pr.new/@tanstack/router-vite-plugin@8268

      @tanstack/solid-router

      npm i https://pkg.pr.new/@tanstack/solid-router@8268

      @tanstack/solid-router-devtools

      npm i https://pkg.pr.new/@tanstack/solid-router-devtools@8268

      @tanstack/solid-router-ssr-query

      npm i https://pkg.pr.new/@tanstack/solid-router-ssr-query@8268

      @tanstack/solid-start

      npm i https://pkg.pr.new/@tanstack/solid-start@8268

      @tanstack/solid-start-client

      npm i https://pkg.pr.new/@tanstack/solid-start-client@8268

      @tanstack/solid-start-server

      npm i https://pkg.pr.new/@tanstack/solid-start-server@8268

      @tanstack/start-client-core

      npm i https://pkg.pr.new/@tanstack/start-client-core@8268

      @tanstack/start-fn-stubs

      npm i https://pkg.pr.new/@tanstack/start-fn-stubs@8268

      @tanstack/start-plugin-core

      npm i https://pkg.pr.new/@tanstack/start-plugin-core@8268

      @tanstack/start-server-core

      npm i https://pkg.pr.new/@tanstack/start-server-core@8268

      @tanstack/start-static-server-functions

      npm i https://pkg.pr.new/@tanstack/start-static-server-functions@8268

      @tanstack/start-storage-context

      npm i https://pkg.pr.new/@tanstack/start-storage-context@8268

      @tanstack/valibot-adapter

      npm i https://pkg.pr.new/@tanstack/valibot-adapter@8268

      @tanstack/virtual-file-routes

      npm i https://pkg.pr.new/@tanstack/virtual-file-routes@8268

      @tanstack/vue-router

      npm i https://pkg.pr.new/@tanstack/vue-router@8268

      @tanstack/vue-router-devtools

      npm i https://pkg.pr.new/@tanstack/vue-router-devtools@8268

      @tanstack/vue-router-ssr-query

      npm i https://pkg.pr.new/@tanstack/vue-router-ssr-query@8268

      @tanstack/vue-start

      npm i https://pkg.pr.new/@tanstack/vue-start@8268

      @tanstack/vue-start-client

      npm i https://pkg.pr.new/@tanstack/vue-start-client@8268

      @tanstack/vue-start-server

      npm i https://pkg.pr.new/@tanstack/vue-start-server@8268

      @tanstack/zod-adapter

      npm i https://pkg.pr.new/@tanstack/zod-adapter@8268

      commit: feb1906

    9. Merging this PR will not alter performance

      1 warning, 1 note

      :warning: 36 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

      :information_source: 20 benchmarks have no flamegraph

      The flamegraph wasn't generated: most of the time was spent in runtime internals, which would leave nothing useful to analyze.

      See affected benchmarks

      ✅ 194 untouched benchmarks ⏩ 3 skipped benchmarks1


      Comparing fix/start-hydration-replay-cleanup (feb1906) with main (6b9fe6d)[^unexpected-base] 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. 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)

Sign in to join this conversation.