fix(solid-router): hydration mismatch for ssr:false routes with pendingComponent by brenelz · Pull Request #7608 · TanStack/router

brenelz · 2026-06-11T23:58:57Z

Problem

ssr: false routes with a pendingComponent fail during dev hydration with template is not a function and never render the loaded component.

Selective SSR routes render the pending component inside the suspense boundary on the server and skip the suspense fallback. On the client, #7266 only skipped the fallback for ssr: 'data-only', so hydrating an ssr: false route rendered a suspense fallback with no matching server markup — a hydration mismatch.

Solution

The naive fix suggested in the issue (skipping the fallback for all selective SSR routes on the client too) regresses client-side navigation: the existing unit test Router.preload="intent", pendingComponent renders during unresolved route loader fails because the pending UI never shows when navigating to an ssr: false route in the browser.

Instead, skip the fallback only when it would conflict with server markup: on the server, and on the client while hydrating (detected via solid-js's sharedConfig.context, which is only set during hydration). Client-side navigations and pure CSR keep their pending fallback. As a side effect this also restores the client-nav pending fallback for data-only routes, which #7266 had over-broadly removed.

Testing

Reproduced the bug in the selective-ssr example dev server before the fix; after the fix both the ssr: false and data-only pending-component routes hydrate cleanly with zero browser errors and reach the loaded state.
All 813 solid-router unit tests pass, including the client-nav pending test that the naive fix broke.
Full selective-ssr e2e suite passes (10/10), including a new ssr: false regression test mirroring the issue's MRE.

Note: the e2e suite runs against a production build where the original bug didn't reproduce, so the new test guards the markup contract; the dev-mode failure was verified manually as described above.

🤖 Generated with Claude Code

Summary by CodeRabbit

Bug Fixes
- Fixed hydration mismatches for routes configured with ssr: false and pendingComponent. Routes now skip the suspense fallback during server-side hydration while properly displaying the pending component on client-side navigation.
Tests
- Added end-to-end test coverage for pending component hydration behavior on selective SSR routes.

…ngComponent Selective SSR routes render the pending component inside the suspense boundary on the server and skip the suspense fallback. On the client, the fallback was only skipped for ssr: 'data-only', so hydrating an ssr: false route rendered a fallback with no matching server markup, crashing dev hydration with "template is not a function". Skip the fallback only while actually hydrating (via solid-js sharedConfig.context) so client-side navigations and pure CSR keep showing the pending component while the match suspends. Fixes TanStack#7283 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

coderabbitai · 2026-06-11T23:59:13Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9500981e-d425-493f-a2fb-80f4a4472708

📥 Commits

Reviewing files that changed from the base of the PR and between 96eca43 and 0cf3e3a.

📒 Files selected for processing (5)

.changeset/lucky-windows-shake.md
e2e/solid-start/selective-ssr/src/routeTree.gen.ts
e2e/solid-start/selective-ssr/src/routes/ssr-false-pending-component.tsx
e2e/solid-start/selective-ssr/tests/pending-component-hydration.spec.ts
packages/solid-router/src/Match.tsx

📝 Walkthrough

Walkthrough

This PR fixes hydration mismatches for Solid Router ssr: false routes that define a pendingComponent. The core change updates suspense fallback logic in Match.tsx to skip the fallback during hydration when selective SSR is configured, allowing server-rendered markup to hydrate cleanly while preserving the pending component for client-side navigations.

Changes

Hydration fix and E2E validation

Layer / File(s)	Summary
Core hydration fix for selective SSR `packages/solid-router/src/Match.tsx`	`shouldSkipSuspenseFallback` now checks `resolvedNoSsr` (true for `ssr: false` and `ssr: 'data-only'`) combined with either server-side execution or presence of `Solid.sharedConfig.context` on the client, replacing the prior client-only data-only check. Inline comment describing data-only behavior is removed.
E2E test route with pending component `e2e/solid-start/selective-ssr/src/routes/ssr-false-pending-component.tsx`	Route defines `ssr: false`, async loader delaying 1.5s, `pendingComponent` rendering a placeholder div, and component rendering a loader-finished marker plus JSON-formatted loader data.
Route tree registration `e2e/solid-start/selective-ssr/src/routeTree.gen.ts`	Generated route module import, route creation via `.update(...)`, type-level registries extended for `'/ssr-false-pending-component'`, and `rootRouteChildren` entry added.
E2E test validation `e2e/solid-start/selective-ssr/tests/pending-component-hydration.spec.ts`	Playwright test navigates to `/ssr-false-pending-component`, verifies URL, checks pending element presence, confirms ready label becomes `OK - loader finished`, and asserts browser errors exclude hydration mismatch and template errors.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

package: solid-start

Poem

🐰 A route that refused to hydrate clear,
Now skips its suspense veil when SSR≠true,
The pending stays pending on client-side view,
But hydration succeeds without template fear! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main fix: addressing hydration mismatch for ssr:false routes with pendingComponent, which is the core focus of this PR.
Linked Issues check	✅ Passed	Changes directly address issue `#7283`: the Match.tsx fix implements conditional fallback skipping on hydration/server, the new test validates ssr:false+pendingComponent hydration, and the new route reproduces the tested scenario.
Out of Scope Changes check	✅ Passed	All changes are scoped to fixing `#7283`: Match.tsx hydration logic, a test route with pending component, test assertions for hydration errors, and changeset documentation. No extraneous modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

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 and usage tips.}

nx-cloud · 2026-06-11T23:59:27Z

View your CI Pipeline Execution ↗ for commit 0cf3e3a

Command	Status	Duration	Result
`nx affected --targets=test:eslint,test:unit,tes...`	✅ Succeeded	8m 7s	View ↗
`nx run-many --target=build --exclude=examples/*...`	✅ Succeeded	2m 23s	View ↗

☁️ Nx Cloud last updated this comment at 2026-06-12 00:08:11 UTC

pkg-pr-new · 2026-06-12T00:04:00Z

More templates

@tanstack/arktype-adapter

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

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-rsc

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: 0cf3e3a

codspeed-hq · 2026-06-12T00:16:34Z

Merging this PR will not alter performance

✅ 6 untouched benchmarks

_{Comparing brenelz:fix/solid-ssr-false-pending-component-hydration (0cf3e3a) with main (96eca43)}

brenelz requested a review from birkskyum June 12, 2026 00:01

birkskyum approved these changes Jun 12, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(solid-router): hydration mismatch for ssr:false routes with pendingComponent#7608

fix(solid-router): hydration mismatch for ssr:false routes with pendingComponent#7608
brenelz wants to merge 1 commit into
TanStack:mainfrom
brenelz:fix/solid-ssr-false-pending-component-hydration

brenelz commented Jun 11, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 11, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Suggested labels

Poem

❌ Failed checks (1 warning)

Uh oh!

nx-cloud Bot commented Jun 11, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Jun 12, 2026

Uh oh!

codspeed-hq Bot commented Jun 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

brenelz commented Jun 11, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Testing

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Suggested labels

Poem

❌ Failed checks (1 warning)

Uh oh!

nx-cloud Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Jun 12, 2026

Uh oh!

codspeed-hq Bot commented Jun 12, 2026

Merging this PR will not alter performance

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

brenelz commented Jun 11, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 11, 2026 •

edited

Loading

nx-cloud Bot commented Jun 11, 2026 •

edited

Loading