Skip to content
Source
Sign inSign up
TanStack/router

fix: keep server-rendered pending UI of no-SSR routes through hydration (take 2) #8649

OpenSheraff(GitHub profile, opens in a new tab)wants to merge 2 commits intomain fromfix/no-ssr-hydration-v2opened

🎯 Changes

Fixes #8640. Replaces #8643, which was reverted in #8646 because of a React hydration mismatch on no-SSR routes without a pendingComponent.

All adapters (same as #8643): a no-SSR match renders its server pending UI through the normal pending path, so hydration renders it at the same position. The ClientOnly wrapper (and Solid's shouldSkipSuspenseFallback) is removed.

React only. React can hydrate a route's Suspense boundary after the shell commits, and the client load can commit in between. @tanstack/react-store's useSelector passes the same function as client and server snapshot, so that late hydration render read the live store (success) against the server's pending HTML. Before, with a pendingComponent, pendingMinMs (default 500 ms) happened to hold the match pending long enough. Without one, it committed at once.

  • hydrate() keeps the matches it presented on router._hydrated. Match reads its store with React.useSyncExternalStore, using that match as the server snapshot.
  • MatchInner doesn't suspend over its own pending UI rendered in place. Doing so would hide it and mount a second copy. It still suspends to keep committed content or errors alive. A ref tracks the in-place state; it starts true for the hydrated pending match.
const match = React.useSyncExternalStore(
  subscribe,
  () => matchStore.get(),
  () =>
    router._hydrated?.find((hydrated) => hydrated.routeId === routeId) ??
    matchStore.get(),
)!

Tests (first commit, in each adapter):

  • issue-8640-data-only-pending-hydration: real SSR + hydration for success, error, notFound, unmatched URL, ssr: false invalid search, and a failing child. Each case runs with a pendingComponent (single server skeleton, held for pendingMinMs) and without one (no hydration mismatch).
  • no-ssr-client-navigation: SSR + hydration, then a param navigation. The client route tree has no ssr, as Start's client build strips it. The component must keep its state. React also shows pending UI during the navigation.

Removing any React piece fails tests: the server snapshot (7), the hydration seed (1), the layout-effect update (2).

Open question: router._hydrated keeps the first page's presented matches (including loader data) for the router's lifetime, because a boundary can hydrate arbitrarily late.

Found while testing, not changed here: in Solid and Vue, a param navigation that shows pending UI remounts the route component, also for ssr: true routes.

Bundle-size pass not done yet.

AI-assisted (Claude).

✅ 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).

🤖 Generated with Claude Code

    1. 🦋 Changeset detected

      Latest commit: 95a17945a425fad8f280ec12f06c3ef04db8f89b

      The changes in this PR will be included in the next version bump.

      This PR includes changesets to release 23 packages
      NameType
      @tanstack/router-corePatch
      @tanstack/react-routerPatch
      @tanstack/solid-routerPatch
      @tanstack/vue-routerPatch
      @tanstack/react-start-clientPatch
      @tanstack/react-start-rscPatch
      @tanstack/react-start-serverPatch
      @tanstack/router-generatorPatch
      @tanstack/router-pluginPatch
      @tanstack/solid-start-clientPatch
      @tanstack/solid-start-serverPatch
      @tanstack/start-client-corePatch
      @tanstack/start-plugin-corePatch
      @tanstack/start-server-corePatch
      @tanstack/start-storage-contextPatch
      @tanstack/vue-start-clientPatch
      @tanstack/vue-start-serverPatch
      @tanstack/react-startPatch
      @tanstack/solid-startPatch
      @tanstack/vue-startPatch
      @tanstack/router-cliPatch
      @tanstack/router-vite-pluginPatch
      @tanstack/start-static-server-functionsPatch

      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

    2. Important

      Draft PR not reviewed

      Draft PRs are not automatically reviewed by default.

      • Trigger a manual review

      To automatically review draft PRs, update your CodeRabbit configuration:

      reviews:
        auto_review:
          drafts: true
      • 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.
    3. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: react-router

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

    5. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: solid-router

    6. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: vue-router

    7. 🚀 Changeset Version Preview

      5 package(s) bumped directly, 19 bumped as dependents.

      🟩 Patch bumps

      PackageVersionReason
      @tanstack/history1.162.4 → 1.162.5Changeset
      @tanstack/react-router1.170.41 → 1.170.42Changeset
      @tanstack/router-core1.171.34 → 1.171.35Changeset
      @tanstack/solid-router1.170.38 → 1.170.39Changeset
      @tanstack/vue-router1.170.37 → 1.170.38Changeset
      @tanstack/react-start1.168.60 → 1.168.61Dependent
      @tanstack/react-start-client1.168.39 → 1.168.40Dependent
      @tanstack/react-start-rsc0.1.59 → 0.1.60Dependent
      @tanstack/react-start-server1.167.46 → 1.167.47Dependent
      @tanstack/router-cli1.167.40 → 1.167.41Dependent
      @tanstack/router-generator1.167.40 → 1.167.41Dependent
      @tanstack/router-plugin1.168.42 → 1.168.43Dependent
      @tanstack/router-vite-plugin1.167.42 → 1.167.43Dependent
      @tanstack/solid-start1.168.57 → 1.168.58Dependent
      @tanstack/solid-start-client1.168.37 → 1.168.38Dependent
      @tanstack/solid-start-server1.167.44 → 1.167.45Dependent
      @tanstack/start-client-core1.170.34 → 1.170.35Dependent
      @tanstack/start-plugin-core1.171.49 → 1.171.50Dependent
      @tanstack/start-server-core1.169.39 → 1.169.40Dependent
      @tanstack/start-static-server-functions1.167.39 → 1.167.40Dependent
      @tanstack/start-storage-context1.167.36 → 1.167.37Dependent
      @tanstack/vue-start1.168.56 → 1.168.57Dependent
      @tanstack/vue-start-client1.167.40 → 1.167.41Dependent
      @tanstack/vue-start-server1.167.44 → 1.167.45Dependent
    8. View your CI Pipeline Execution ↗ for commit 95a17945a425fad8f280ec12f06c3ef04db8f89b

      CommandStatusDurationResult
      nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded12m 25sView ↗
      nx run-many --target=build --exclude=examples/*...✅ Succeeded2m 8sView ↗

      ☁️ Nx Cloud last updated this comment at 2026-10-09 20:34:22 UTC

    9. Bundle Size Benchmarks

      • Commit: 83e1806cf7e0
      • Measured at: 2026-10-09T20:20:50.791Z
      • Baseline source: history:f6d21de12b69
      • Dashboard: bundle-size history

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

      ScenarioCurrent (gzip)Initial (gzip)RawBrotliTrend
      react-router.minimal84.0 KiB
      +4 B
      83.8 KiB
      +5 B
      261.4 KiB
      +20 B
      73.3 KiB
      +90 B
      ▅▅███████▁██
      react-router.full87.6 KiB
      +61 B
      87.4 KiB
      +62 B
      273.4 KiB
      +223 B
      76.5 KiB
      +108 B
      ▁▁▄▄▄▄▄▄▄▃▄█
      solid-router.minimal33.4 KiB
      -80 B
      33.3 KiB
      -83 B
      95.3 KiB
      -447 B
      30.2 KiB
      -138 B
      ██▆▆▆▆▆▆▆▁▆▁
      solid-router.full38.3 KiB
      -62 B
      38.2 KiB
      -61 B
      110.2 KiB
      -302 B
      34.6 KiB
      -97 B
      ██▇▇▇▇▇▇▇▁▇▁
      vue-router.minimal49.4 KiB
      -48 B
      49.3 KiB
      -50 B
      136.4 KiB
      -166 B
      44.7 KiB
      -105 B
      ▂▂███████▁█▁
      vue-router.full55.0 KiB
      -45 B
      54.9 KiB
      -46 B
      154.7 KiB
      -166 B
      49.7 KiB
      -144 B
      ▁▁███████▁█▁
      react-start.minimal96.8 KiB
      +65 B
      96.6 KiB
      +64 B
      302.4 KiB
      +150 B
      84.0 KiB
      +116 B
      ██▇▇▇▇▇▇▃▁▃█
      react-start.query-integration104.2 KiB
      +65 B
      104.1 KiB
      +61 B
      329.0 KiB
      +158 B
      90.6 KiB
      +160 B
      ▆▆▇▇▇▇▇▇▃▁▃█
      react-start.deferred-hydration97.5 KiB
      +64 B
      96.7 KiB
      +62 B
      303.7 KiB
      +150 B
      84.7 KiB
      +44 B
      ▇▇▇▇▇▇▇▇▃▁▃█
      react-start.full100.0 KiB
      +75 B
      99.8 KiB
      +75 B
      312.2 KiB
      +238 B
      86.7 KiB
      -9 B
      ▄▄▆▆▆▆▆▆▂▁▂█
      react-start.rsbuild.minimal100.4 KiB
      +58 B
      100.2 KiB
      +58 B
      313.3 KiB
      +128 B
      86.7 KiB
      +67 B
      ▃▃██████▃▁▃█
      react-start.rsbuild.minimal-iife100.8 KiB
      +58 B
      100.6 KiB
      +58 B
      314.3 KiB
      +128 B
      87.0 KiB
      +47 B
      ▃▃██████▃▁▃█
      react-start.rsbuild.full103.7 KiB
      +85 B
      103.5 KiB
      +85 B
      323.6 KiB
      +238 B
      89.4 KiB
      +28 B
      ▂▂▆▆▆▆▆▆▂▁▂█
      solid-start.minimal46.2 KiB
      -67 B
      46.1 KiB
      -66 B
      135.0 KiB
      -431 B
      41.2 KiB
      -35 B
      ██▅▅▅▅▅▅▄▁▄▁
      solid-start.deferred-hydration49.2 KiB
      -84 B
      46.1 KiB
      -83 B
      142.4 KiB
      -437 B
      44.0 KiB
      -39 B
      ██▅▅▅▅▅▅▄▁▄▁
      solid-start.full51.3 KiB
      -43 B
      51.2 KiB
      -45 B
      150.6 KiB
      -285 B
      45.6 KiB
      +10 B
      ██▆▆▆▆▆▆▄▁▄▁
      vue-start.minimal65.4 KiB
      -46 B
      65.3 KiB
      -47 B
      185.8 KiB
      -152 B
      58.4 KiB
      -84 B
      ▇▇██████▅▁▅▁
      vue-start.full69.2 KiB
      -55 B
      69.1 KiB
      -52 B
      198.1 KiB
      -152 B
      61.7 KiB
      -94 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.

    10. More templates

      @tanstack/arktype-adapter

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

      @tanstack/eslint-plugin-router

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

      @tanstack/eslint-plugin-start

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

      @tanstack/history

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

      @tanstack/nitro-v2-vite-plugin

      npm i https://pkg.pr.new/@tanstack/nitro-v2-vite-plugin@8649

      @tanstack/react-router

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

      @tanstack/react-router-devtools

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

      @tanstack/react-router-ssr-query

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

      @tanstack/react-start

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

      @tanstack/react-start-client

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

      @tanstack/react-start-rsc

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

      @tanstack/react-start-server

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

      @tanstack/router-cli

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

      @tanstack/router-core

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

      @tanstack/router-devtools

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

      @tanstack/router-devtools-core

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

      @tanstack/router-generator

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

      @tanstack/router-plugin

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

      @tanstack/router-ssr-query-core

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

      @tanstack/router-utils

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

      @tanstack/router-vite-plugin

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

      @tanstack/solid-router

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

      @tanstack/solid-router-devtools

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

      @tanstack/solid-router-ssr-query

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

      @tanstack/solid-start

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

      @tanstack/solid-start-client

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

      @tanstack/solid-start-server

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

      @tanstack/start-client-core

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

      @tanstack/start-fn-stubs

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

      @tanstack/start-plugin-core

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

      @tanstack/start-server-core

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

      @tanstack/start-static-server-functions

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

      @tanstack/start-storage-context

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

      @tanstack/valibot-adapter

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

      @tanstack/virtual-file-routes

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

      @tanstack/vue-router

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

      @tanstack/vue-router-devtools

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

      @tanstack/vue-router-ssr-query

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

      @tanstack/vue-start

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

      @tanstack/vue-start-client

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

      @tanstack/vue-start-server

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

      @tanstack/zod-adapter

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

      commit: 95a1794

    11. Merging this PR will regress 4 benchmarks

      :information_source: 3 benchmarks have no flame graph

      The flamegraph could not be generated because too much time was spent in runtime internals, making the visualization not useful for performance analysis.

      :warning: Different runtime environments detected

      Some benchmarks with significant performance changes were compared across different runtime environments, which may affect the accuracy of the results.

      Open the report in CodSpeed to investigate

      ⚡ 17 improved benchmarks ❌ 4 regressed benchmarks ✅ 173 untouched benchmarks ⏩ 3 skipped benchmarks1

      Warning

      Please fix the performance issues or acknowledge them on CodSpeed.

      Performance Changes

      ModeBenchmarkBASEHEADEfficiency
      ❌Memorymem client unique-location-churn (react)68.1 KB77.2 KB-11.77%
      ❌Memorymem server aborted-requests (solid)142.9 KB151.9 KB-5.89%
      ❌Memorymem server request-churn (solid)129.5 KB134.4 KB-3.66%
      ❌Memorymem client unique-location-churn (solid)61.5 KB63.7 KB-3.33%
      ⚡Simulationclient-nested-params navigation loop (solid)761.7 ms691.1 ms+10.21%
      ⚡Memorymem client navigation-churn (solid)88.6 KB80.4 KB+10.2%
      ⚡Memorymem client unique-location-churn (vue)96.2 KB88.9 KB+8.3%
      ⚡Simulationclient-history navigation loop (solid)93.9 ms87.9 ms+6.81%
      ⚡Simulationclient-route-tree-scale navigation loop (solid)220.1 ms206.1 ms+6.79%
      ⚡Simulationclient-rewrites navigation loop (solid)128.2 ms120.4 ms+6.55%
      ⚡Memorymem client preload-churn (solid)76.2 KB71.9 KB+5.99%
      ⚡Memorymem client mount-unmount (solid)80.9 KB76.4 KB+5.9%
      ⚡Simulationclient-async-pipeline navigation loop (solid)113 ms107.2 ms+5.43%
      ⚡Simulationclient-control-flow navigation loop (solid)99 ms94.1 ms+5.23%
      ⚡Simulationclient-loaders navigation loop (solid)144.1 ms137.3 ms+4.97%
      ⚡Memorymem server error-paths not-found (vue)127.8 KB122.4 KB+4.42%
      ⚡Simulationclient-preload interaction loop (solid)151 ms144.6 ms+4.41%
      ⚡Simulationclient-head navigation loop (solid)401.7 ms387.9 ms+3.55%
      ⚡ :information_source:Simulationclient-search-params navigation loop (solid)223.6 ms216.5 ms+3.31%
      ⚡Simulationclient-mount loop (solid)90.5 ms87.6 ms+3.3%
      ..................

      :information_source: Only the first 20 benchmarks are displayed. Go to the app to view all benchmarks.

      [!TIP] Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.


      Comparing fix/no-ssr-hydration-v2 (95a1794) with main (f6d21de) 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. ↩

Sign in to join this conversation.