Skip to content

Commit 0cf3e3a

Browse files
brenelzclaude
andcommitted
fix(solid-router): hydration mismatch for ssr:false routes with pendingComponent
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 #7283 Co-Authored-By: Claude Fable 5 <[email protected]>
1 parent 96eca43 commit 0cf3e3a

5 files changed

Lines changed: 102 additions & 7 deletions

File tree

‎.changeset/lucky-windows-shake.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@tanstack/solid-router': patch
3+
---
4+
5+
Fix hydration mismatch for `ssr: false` routes with a `pendingComponent`. The suspense fallback is now skipped only while hydrating server-rendered markup, so selective SSR routes hydrate cleanly while client-side navigations keep showing their pending component.

‎e2e/solid-start/selective-ssr/src/routeTree.gen.ts‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,18 @@
99
// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
1010

1111
import { Route as rootRouteImport } from './routes/__root'
12+
import { Route as SsrFalsePendingComponentRouteImport } from './routes/ssr-false-pending-component'
1213
import { Route as PostsRouteImport } from './routes/posts'
1314
import { Route as DataOnlyPendingComponentRouteImport } from './routes/data-only-pending-component'
1415
import { Route as IndexRouteImport } from './routes/index'
1516
import { Route as PostsPostIdRouteImport } from './routes/posts.$postId'
1617

18+
const SsrFalsePendingComponentRoute =
19+
SsrFalsePendingComponentRouteImport.update({
20+
id: '/ssr-false-pending-component',
21+
path: '/ssr-false-pending-component',
22+
getParentRoute: () => rootRouteImport,
23+
} as any)
1724
const PostsRoute = PostsRouteImport.update({
1825
id: '/posts',
1926
path: '/posts',
@@ -40,42 +47,64 @@ export interface FileRoutesByFullPath {
4047
'/': typeof IndexRoute
4148
'/data-only-pending-component': typeof DataOnlyPendingComponentRoute
4249
'/posts': typeof PostsRouteWithChildren
50+
'/ssr-false-pending-component': typeof SsrFalsePendingComponentRoute
4351
'/posts/$postId': typeof PostsPostIdRoute
4452
}
4553
export interface FileRoutesByTo {
4654
'/': typeof IndexRoute
4755
'/data-only-pending-component': typeof DataOnlyPendingComponentRoute
4856
'/posts': typeof PostsRouteWithChildren
57+
'/ssr-false-pending-component': typeof SsrFalsePendingComponentRoute
4958
'/posts/$postId': typeof PostsPostIdRoute
5059
}
5160
export interface FileRoutesById {
5261
__root__: typeof rootRouteImport
5362
'/': typeof IndexRoute
5463
'/data-only-pending-component': typeof DataOnlyPendingComponentRoute
5564
'/posts': typeof PostsRouteWithChildren
65+
'/ssr-false-pending-component': typeof SsrFalsePendingComponentRoute
5666
'/posts/$postId': typeof PostsPostIdRoute
5767
}
5868
export interface FileRouteTypes {
5969
fileRoutesByFullPath: FileRoutesByFullPath
60-
fullPaths: '/' | '/data-only-pending-component' | '/posts' | '/posts/$postId'
70+
fullPaths:
71+
| '/'
72+
| '/data-only-pending-component'
73+
| '/posts'
74+
| '/ssr-false-pending-component'
75+
| '/posts/$postId'
6176
fileRoutesByTo: FileRoutesByTo
62-
to: '/' | '/data-only-pending-component' | '/posts' | '/posts/$postId'
77+
to:
78+
| '/'
79+
| '/data-only-pending-component'
80+
| '/posts'
81+
| '/ssr-false-pending-component'
82+
| '/posts/$postId'
6383
id:
6484
| '__root__'
6585
| '/'
6686
| '/data-only-pending-component'
6787
| '/posts'
88+
| '/ssr-false-pending-component'
6889
| '/posts/$postId'
6990
fileRoutesById: FileRoutesById
7091
}
7192
export interface RootRouteChildren {
7293
IndexRoute: typeof IndexRoute
7394
DataOnlyPendingComponentRoute: typeof DataOnlyPendingComponentRoute
7495
PostsRoute: typeof PostsRouteWithChildren
96+
SsrFalsePendingComponentRoute: typeof SsrFalsePendingComponentRoute
7597
}
7698

7799
declare module '@tanstack/solid-router' {
78100
interface FileRoutesByPath {
101+
'/ssr-false-pending-component': {
102+
id: '/ssr-false-pending-component'
103+
path: '/ssr-false-pending-component'
104+
fullPath: '/ssr-false-pending-component'
105+
preLoaderRoute: typeof SsrFalsePendingComponentRouteImport
106+
parentRoute: typeof rootRouteImport
107+
}
79108
'/posts': {
80109
id: '/posts'
81110
path: '/posts'
@@ -121,6 +150,7 @@ const rootRouteChildren: RootRouteChildren = {
121150
IndexRoute: IndexRoute,
122151
DataOnlyPendingComponentRoute: DataOnlyPendingComponentRoute,
123152
PostsRoute: PostsRouteWithChildren,
153+
SsrFalsePendingComponentRoute: SsrFalsePendingComponentRoute,
124154
}
125155
export const routeTree = rootRouteImport
126156
._addFileChildren(rootRouteChildren)
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
import { createFileRoute } from '@tanstack/solid-router'
2+
import { z } from 'zod'
3+
import { ssrSchema } from '~/search'
4+
5+
export const Route = createFileRoute('/ssr-false-pending-component')({
6+
validateSearch: z.object({ root: ssrSchema }),
7+
ssr: false,
8+
loader: async () => {
9+
await new Promise((resolve) => setTimeout(resolve, 1500))
10+
return { loadedAt: new Date().toISOString() }
11+
},
12+
pendingComponent: () => (
13+
<div data-testid="ssr-false-pending-component-pending" />
14+
),
15+
component: SsrFalsePendingComponentRoute,
16+
})
17+
18+
function SsrFalsePendingComponentRoute() {
19+
const data = Route.useLoaderData()
20+
21+
return (
22+
<div data-testid="ssr-false-pending-component-ready">
23+
<p data-testid="ssr-false-pending-component-ready-label">
24+
OK - loader finished
25+
</p>
26+
<pre data-testid="ssr-false-pending-component-ready-data">
27+
{JSON.stringify(data(), null, 2)}
28+
</pre>
29+
</div>
30+
)
31+
}

‎e2e/solid-start/selective-ssr/tests/pending-component-hydration.spec.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,30 @@ test.describe('pending component hydration', () => {
2727
expect.stringContaining('Hydration Mismatch'),
2828
)
2929
})
30+
31+
test('ssr:false route hydrates from pending element to loaded state on first load', async ({
32+
page,
33+
}) => {
34+
const browserErrors = collectBrowserErrors(page)
35+
36+
await page.goto('/ssr-false-pending-component')
37+
38+
await expect(page).toHaveURL(/ssr-false-pending-component/)
39+
40+
await expect(
41+
page.getByTestId('ssr-false-pending-component-pending'),
42+
).toBeAttached()
43+
44+
await expect(
45+
page.getByTestId('ssr-false-pending-component-ready-label'),
46+
).toHaveText('OK - loader finished', { timeout: 10_000 })
47+
48+
expect(browserErrors).toEqual([])
49+
expect(browserErrors).not.toContainEqual(
50+
expect.stringContaining('template is not a function'),
51+
)
52+
expect(browserErrors).not.toContainEqual(
53+
expect.stringContaining('Hydration Mismatch'),
54+
)
55+
})
3056
})

‎packages/solid-router/src/Match.tsx‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -86,10 +86,15 @@ export const Match = (props: { matchId: string }) => {
8686
currentMatchState().ssr === false ||
8787
currentMatchState().ssr === 'data-only'
8888

89+
// Selective SSR (`ssr: false` and `ssr: 'data-only'`) renders the
90+
// pending component inside the suspense boundary on the server, so
91+
// rendering a suspense fallback while hydrating would try to claim
92+
// markup the server never sent, causing a hydration mismatch. Outside
93+
// of hydration (client-side navigation or pure CSR) the fallback must
94+
// stay so the pending component can show while the match suspends.
8995
const shouldSkipSuspenseFallback =
90-
(isServer ?? router.isServer)
91-
? resolvedNoSsr
92-
: currentMatchState().ssr === 'data-only'
96+
resolvedNoSsr &&
97+
((isServer ?? router.isServer) || !!Solid.sharedConfig.context)
9398

9499
const ResolvedSuspenseBoundary = () => Solid.Suspense
95100

@@ -110,8 +115,6 @@ export const Match = (props: { matchId: string }) => {
110115
<Dynamic
111116
component={ResolvedSuspenseBoundary()}
112117
fallback={
113-
// Data-only SSR renders the inner fallback on the server, so
114-
// avoid adding an extra suspense fallback on the client.
115118
shouldSkipSuspenseFallback ? undefined : (
116119
<Dynamic component={resolvePendingComponent()} />
117120
)

0 commit comments

Comments
 (0)