fix: keep server-rendered pending UI of no-SSR routes through hydration (take 2) #8649
main fromfix/no-ssr-hydration-v2·opened 🎯 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 onrouter._hydrated.Matchreads its store withReact.useSyncExternalStore, using that match as the server snapshot.MatchInnerdoesn'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 startstruefor 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: falseinvalid search, and a failing child. Each case runs with apendingComponent(single server skeleton, held forpendingMinMs) and without one (no hydration mismatch).no-ssr-client-navigation: SSR + hydration, then a param navigation. The client route tree has nossr, 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
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.
Comment `@coderabbitai help` to get the list of available commands.github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: react-router
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-core
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: solid-router
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: vue-router
🚀 Changeset Version Preview#
5 package(s) bumped directly, 19 bumped as dependents.
🟩 Patch bumps#
Package Version Reason @tanstack/history1.162.4 → 1.162.5 Changeset @tanstack/react-router1.170.41 → 1.170.42 Changeset @tanstack/router-core1.171.34 → 1.171.35 Changeset @tanstack/solid-router1.170.38 → 1.170.39 Changeset @tanstack/vue-router1.170.37 → 1.170.38 Changeset @tanstack/react-start1.168.60 → 1.168.61 Dependent @tanstack/react-start-client1.168.39 → 1.168.40 Dependent @tanstack/react-start-rsc0.1.59 → 0.1.60 Dependent @tanstack/react-start-server1.167.46 → 1.167.47 Dependent @tanstack/router-cli1.167.40 → 1.167.41 Dependent @tanstack/router-generator1.167.40 → 1.167.41 Dependent @tanstack/router-plugin1.168.42 → 1.168.43 Dependent @tanstack/router-vite-plugin1.167.42 → 1.167.43 Dependent @tanstack/solid-start1.168.57 → 1.168.58 Dependent @tanstack/solid-start-client1.168.37 → 1.168.38 Dependent @tanstack/solid-start-server1.167.44 → 1.167.45 Dependent @tanstack/start-client-core1.170.34 → 1.170.35 Dependent @tanstack/start-plugin-core1.171.49 → 1.171.50 Dependent @tanstack/start-server-core1.169.39 → 1.169.40 Dependent @tanstack/start-static-server-functions1.167.39 → 1.167.40 Dependent @tanstack/start-storage-context1.167.36 → 1.167.37 Dependent @tanstack/vue-start1.168.56 → 1.168.57 Dependent @tanstack/vue-start-client1.167.40 → 1.167.41 Dependent @tanstack/vue-start-server1.167.44 → 1.167.45 Dependent View your CI Pipeline Execution ↗ for commit 95a17945a425fad8f280ec12f06c3ef04db8f89b
Command Status Duration Result nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded 12m 25s View ↗ nx run-many --target=build --exclude=examples/*...✅ Succeeded 2m 8s View ↗
☁️ Nx Cloud last updated this comment at
2026-10-09 20:34:22UTCBundle 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:
Scenario Current (gzip) Initial (gzip) Raw Brotli Trend react-router.minimal84.0 KiB
+4 B83.8 KiB
+5 B261.4 KiB
+20 B73.3 KiB
+90 B▅▅███████▁██
react-router.full87.6 KiB
+61 B87.4 KiB
+62 B273.4 KiB
+223 B76.5 KiB
+108 B▁▁▄▄▄▄▄▄▄▃▄█
solid-router.minimal33.4 KiB
-80 B33.3 KiB
-83 B95.3 KiB
-447 B30.2 KiB
-138 B██▆▆▆▆▆▆▆▁▆▁
solid-router.full38.3 KiB
-62 B38.2 KiB
-61 B110.2 KiB
-302 B34.6 KiB
-97 B██▇▇▇▇▇▇▇▁▇▁
vue-router.minimal49.4 KiB
-48 B49.3 KiB
-50 B136.4 KiB
-166 B44.7 KiB
-105 B▂▂███████▁█▁
vue-router.full55.0 KiB
-45 B54.9 KiB
-46 B154.7 KiB
-166 B49.7 KiB
-144 B▁▁███████▁█▁
react-start.minimal96.8 KiB
+65 B96.6 KiB
+64 B302.4 KiB
+150 B84.0 KiB
+116 B██▇▇▇▇▇▇▃▁▃█
react-start.query-integration104.2 KiB
+65 B104.1 KiB
+61 B329.0 KiB
+158 B90.6 KiB
+160 B▆▆▇▇▇▇▇▇▃▁▃█
react-start.deferred-hydration97.5 KiB
+64 B96.7 KiB
+62 B303.7 KiB
+150 B84.7 KiB
+44 B▇▇▇▇▇▇▇▇▃▁▃█
react-start.full100.0 KiB
+75 B99.8 KiB
+75 B312.2 KiB
+238 B86.7 KiB
-9 B▄▄▆▆▆▆▆▆▂▁▂█
react-start.rsbuild.minimal100.4 KiB
+58 B100.2 KiB
+58 B313.3 KiB
+128 B86.7 KiB
+67 B▃▃██████▃▁▃█
react-start.rsbuild.minimal-iife100.8 KiB
+58 B100.6 KiB
+58 B314.3 KiB
+128 B87.0 KiB
+47 B▃▃██████▃▁▃█
react-start.rsbuild.full103.7 KiB
+85 B103.5 KiB
+85 B323.6 KiB
+238 B89.4 KiB
+28 B▂▂▆▆▆▆▆▆▂▁▂█
solid-start.minimal46.2 KiB
-67 B46.1 KiB
-66 B135.0 KiB
-431 B41.2 KiB
-35 B██▅▅▅▅▅▅▄▁▄▁
solid-start.deferred-hydration49.2 KiB
-84 B46.1 KiB
-83 B142.4 KiB
-437 B44.0 KiB
-39 B██▅▅▅▅▅▅▄▁▄▁
solid-start.full51.3 KiB
-43 B51.2 KiB
-45 B150.6 KiB
-285 B45.6 KiB
+10 B██▆▆▆▆▆▆▄▁▄▁
vue-start.minimal65.4 KiB
-46 B65.3 KiB
-47 B185.8 KiB
-152 B58.4 KiB
-84 B▇▇██████▅▁▅▁
vue-start.full69.2 KiB
-55 B69.1 KiB
-52 B198.1 KiB
-152 B61.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.
- Commit:
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-vue-example-basic-jsx
- tanstack-router-vue-example-basic-file-based-jsx
- tanstack-router-vue-example-basic-file-based-sfc
- 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/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@8649commit:
95a1794Merging 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.
⚡ 17improved benchmarks❌ 4regressed benchmarks✅ 173untouched benchmarks⏩ 3skipped benchmarks1Warning
Please fix the performance issues or acknowledge them on CodSpeed.
Performance Changes#
: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 regressionon this PR, or directly use the CodSpeed MCP with your agent.
Comparingfix/no-ssr-hydration-v2(95a1794) withmain(f6d21de)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. ↩
-
Sheraff(GitHub profile, opens in a new tab) linked this to fix #8640
Sign in to join this conversation.
🦋 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
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