Skip to content

Commit 0c25a7b

Browse files
authored
fix(react-router): avoid Suspense above root documents (#8055)
* fix(react-router): avoid suspense above root documents * test(react-start): cover root document hydration * test(react-router): remove indirect hydration assertion * perf(react-router): reduce suspense wrapper bundle size * test(react-start): isolate root hydration regression * fix(react-router): preserve root suspense in CSR * refactor(react-router): simplify root suspense checks * fix(react-router): preserve functional ssr classification
1 parent 31882c7 commit 0c25a7b

15 files changed

Lines changed: 388 additions & 17 deletions

File tree

‎.changeset/fresh-ducks-hydrate.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@tanstack/react-router': patch
3+
---
4+
5+
Avoid wrapping root components that may render the HTML document in a Suspense boundary during SSR and hydration.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
node_modules
2+
dist
3+
test-results
4+
playwright-report
5+
port*.txt
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
src/routeTree.gen.ts
Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
{
2+
"name": "tanstack-react-start-e2e-root-document-hydration",
3+
"private": true,
4+
"sideEffects": false,
5+
"type": "module",
6+
"scripts": {
7+
"dev": "vite dev --port 3000",
8+
"dev:e2e": "vite dev --port $PORT",
9+
"build": "vite build && tsc --noEmit",
10+
"start": "pnpx srvx --prod -s ../client dist/server/server.js",
11+
"test:e2e:dev": "MODE=dev playwright test --project=chromium",
12+
"test:e2e:prod": "MODE=prod playwright test --project=chromium",
13+
"test:e2e": "rm -rf port*.txt; pnpm run test:e2e:dev && pnpm run test:e2e:prod"
14+
},
15+
"dependencies": {
16+
"@tanstack/react-router": "workspace:*",
17+
"@tanstack/react-start": "workspace:*",
18+
"react": "^19.0.0",
19+
"react-dom": "^19.0.0"
20+
},
21+
"devDependencies": {
22+
"@playwright/test": "^1.61.0",
23+
"@tanstack/router-e2e-utils": "workspace:*",
24+
"@types/node": "^22.10.2",
25+
"@types/react": "^19.0.8",
26+
"@types/react-dom": "^19.0.3",
27+
"@vitejs/plugin-react": "^6.0.1",
28+
"srvx": "^0.11.9",
29+
"@typescript/native": "npm:typescript@^7.0.2",
30+
"typescript": "npm:@typescript/typescript6@^6.0.2",
31+
"vite": "^8.0.14"
32+
},
33+
"nx": {
34+
"targets": {
35+
"test:e2e": {
36+
"parallelism": false
37+
}
38+
}
39+
}
40+
}
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
import { defineConfig, devices } from '@playwright/test'
2+
import { getTestServerPort } from '@tanstack/router-e2e-utils'
3+
import packageJson from './package.json' with { type: 'json' }
4+
5+
const isDev = process.env.MODE === 'dev'
6+
const PORT = await getTestServerPort(packageJson.name)
7+
const baseURL = `http://localhost:${PORT}`
8+
9+
export default defineConfig({
10+
testDir: './tests',
11+
workers: 1,
12+
reporter: [['line']],
13+
14+
use: {
15+
baseURL,
16+
},
17+
18+
webServer: {
19+
command: isDev ? 'pnpm dev:e2e' : `pnpm build && PORT=${PORT} pnpm start`,
20+
url: baseURL,
21+
reuseExistingServer: !process.env.CI,
22+
stdout: 'pipe',
23+
env: {
24+
PORT: String(PORT),
25+
},
26+
},
27+
28+
projects: [
29+
{
30+
name: 'chromium',
31+
use: {
32+
...devices['Desktop Chrome'],
33+
},
34+
},
35+
],
36+
})
Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
/* eslint-disable */
2+
3+
// @ts-nocheck
4+
5+
// noinspection JSUnusedGlobalSymbols
6+
7+
// This file was automatically generated by TanStack Router.
8+
// You should NOT make any changes in this file as it will be overwritten.
9+
// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
10+
11+
import { Route as rootRouteImport } from './routes/__root'
12+
import { Route as IndexRouteImport } from './routes/index'
13+
14+
const IndexRoute = IndexRouteImport.update({
15+
id: '/',
16+
path: '/',
17+
getParentRoute: () => rootRouteImport,
18+
} as any)
19+
20+
export interface FileRoutesByFullPath {
21+
'/': typeof IndexRoute
22+
}
23+
export interface FileRoutesByTo {
24+
'/': typeof IndexRoute
25+
}
26+
export interface FileRoutesById {
27+
__root__: typeof rootRouteImport
28+
'/': typeof IndexRoute
29+
}
30+
export interface FileRouteTypes {
31+
fileRoutesByFullPath: FileRoutesByFullPath
32+
fullPaths: '/'
33+
fileRoutesByTo: FileRoutesByTo
34+
to: '/'
35+
id: '__root__' | '/'
36+
fileRoutesById: FileRoutesById
37+
}
38+
export interface RootRouteChildren {
39+
IndexRoute: typeof IndexRoute
40+
}
41+
42+
declare module '@tanstack/react-router' {
43+
interface FileRoutesByPath {
44+
'/': {
45+
id: '/'
46+
path: '/'
47+
fullPath: '/'
48+
preLoaderRoute: typeof IndexRouteImport
49+
parentRoute: typeof rootRouteImport
50+
}
51+
}
52+
}
53+
54+
const rootRouteChildren: RootRouteChildren = {
55+
IndexRoute: IndexRoute,
56+
}
57+
export const routeTree = rootRouteImport
58+
._addFileChildren(rootRouteChildren)
59+
._addFileTypes<FileRouteTypes>()
60+
61+
import type { getRouter } from './router.tsx'
62+
import type { createStart } from '@tanstack/react-start'
63+
declare module '@tanstack/react-start' {
64+
interface Register {
65+
ssr: true
66+
router: Awaited<ReturnType<typeof getRouter>>
67+
}
68+
}
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
import { createRouter } from '@tanstack/react-router'
2+
import { routeTree } from './routeTree.gen'
3+
4+
export function getRouter() {
5+
return createRouter({ routeTree })
6+
}
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
import {
2+
HeadContent,
3+
Outlet,
4+
Scripts,
5+
createRootRoute,
6+
} from '@tanstack/react-router'
7+
import { useEffect } from 'react'
8+
9+
export const Route = createRootRoute({
10+
pendingComponent: () => null,
11+
component: RootComponent,
12+
})
13+
14+
function RootComponent() {
15+
useEffect(() => {
16+
document.documentElement.dataset.hydrated = 'true'
17+
}, [])
18+
19+
return (
20+
<html>
21+
<head>
22+
<HeadContent />
23+
</head>
24+
<body>
25+
<div data-testid="ssr-node" />
26+
<script
27+
dangerouslySetInnerHTML={{
28+
__html: `window.__ssrNode ??= document.currentScript.previousElementSibling`,
29+
}}
30+
/>
31+
<Outlet />
32+
<Scripts />
33+
</body>
34+
</html>
35+
)
36+
}
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
import { createFileRoute } from '@tanstack/react-router'
2+
3+
export const Route = createFileRoute('/')({
4+
component: () => <main>Root document hydration</main>,
5+
})
Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
import { expect } from '@playwright/test'
2+
import { test } from '@tanstack/router-e2e-utils'
3+
4+
test('a root pendingComponent preserves the SSR document during hydration', async ({
5+
page,
6+
}) => {
7+
await page.addInitScript(() => {
8+
const state = { removed: false }
9+
;(window as any).__hydration = state
10+
11+
new MutationObserver((records) => {
12+
const ssrNode = (window as any).__ssrNode as Node | undefined
13+
if (!ssrNode) {
14+
return
15+
}
16+
17+
for (const record of records) {
18+
for (const removedNode of record.removedNodes) {
19+
if (
20+
removedNode === ssrNode ||
21+
(removedNode instanceof Element && removedNode.contains(ssrNode))
22+
) {
23+
state.removed = true
24+
}
25+
}
26+
}
27+
}).observe(document, { childList: true, subtree: true })
28+
})
29+
30+
const response = await page.goto('/')
31+
expect(response?.ok()).toBe(true)
32+
await expect(page.locator('html')).toHaveAttribute('data-hydrated', 'true')
33+
34+
expect(
35+
await page.evaluate(() => ({
36+
captured: !!(window as any).__ssrNode,
37+
removed: (window as any).__hydration.removed,
38+
replaced:
39+
(window as any).__ssrNode !==
40+
document.querySelector('[data-testid="ssr-node"]'),
41+
})),
42+
).toEqual({
43+
captured: true,
44+
removed: false,
45+
replaced: false,
46+
})
47+
})

0 commit comments

Comments
 (0)