diff --git a/e2e/react-start/basic/public/async-user-script.js b/e2e/react-start/basic/public/async-user-script.js
new file mode 100644
index 00000000000..34f4c034c00
--- /dev/null
+++ b/e2e/react-start/basic/public/async-user-script.js
@@ -0,0 +1,2 @@
+console.log('ASYNC_USER_SCRIPT loaded')
+window.ASYNC_USER_SCRIPT = true
diff --git a/e2e/react-start/basic/public/before-scripts-async-script.js b/e2e/react-start/basic/public/before-scripts-async-script.js
new file mode 100644
index 00000000000..7d082fea1c2
--- /dev/null
+++ b/e2e/react-start/basic/public/before-scripts-async-script.js
@@ -0,0 +1,2 @@
+console.log('BEFORE_SCRIPTS_ASYNC_SCRIPT loaded')
+window.BEFORE_SCRIPTS_ASYNC_SCRIPT = true
diff --git a/e2e/react-start/basic/public/before-scripts-script.js b/e2e/react-start/basic/public/before-scripts-script.js
new file mode 100644
index 00000000000..7150d19d40d
--- /dev/null
+++ b/e2e/react-start/basic/public/before-scripts-script.js
@@ -0,0 +1,2 @@
+console.log('BEFORE_SCRIPTS_SCRIPT loaded')
+window.BEFORE_SCRIPTS_SCRIPT = true
diff --git a/e2e/react-start/basic/public/head-async-script.js b/e2e/react-start/basic/public/head-async-script.js
new file mode 100644
index 00000000000..3da8a928cde
--- /dev/null
+++ b/e2e/react-start/basic/public/head-async-script.js
@@ -0,0 +1,2 @@
+console.log('HEAD_ASYNC_SCRIPT loaded')
+window.HEAD_ASYNC_SCRIPT = true
diff --git a/e2e/react-start/basic/public/head-script.js b/e2e/react-start/basic/public/head-script.js
new file mode 100644
index 00000000000..3a64b23438b
--- /dev/null
+++ b/e2e/react-start/basic/public/head-script.js
@@ -0,0 +1,2 @@
+console.log('HEAD_SCRIPT loaded')
+window.HEAD_SCRIPT = true
diff --git a/e2e/react-start/basic/public/user-script.js b/e2e/react-start/basic/public/user-script.js
new file mode 100644
index 00000000000..8d06a610c02
--- /dev/null
+++ b/e2e/react-start/basic/public/user-script.js
@@ -0,0 +1,2 @@
+console.log('USER_SCRIPT loaded')
+window.USER_SCRIPT = true
diff --git a/e2e/react-start/basic/src/routes/__root.tsx b/e2e/react-start/basic/src/routes/__root.tsx
index 581510f616a..3aa315c67e8 100644
--- a/e2e/react-start/basic/src/routes/__root.tsx
+++ b/e2e/react-start/basic/src/routes/__root.tsx
@@ -97,6 +97,8 @@ function RootDocument({ children }: { children: React.ReactNode }) {
+
+
@@ -205,7 +207,11 @@ function RootDocument({ children }: { children: React.ReactNode }) {
+
+
+
+
)
diff --git a/e2e/react-start/basic/tests/root-scripts.spec.ts b/e2e/react-start/basic/tests/root-scripts.spec.ts
new file mode 100644
index 00000000000..80b6d83e40d
--- /dev/null
+++ b/e2e/react-start/basic/tests/root-scripts.spec.ts
@@ -0,0 +1,61 @@
+import { expect } from '@playwright/test'
+import { test } from '@tanstack/router-e2e-utils'
+
+// All user-rendered scripts added in __root.tsx (not via head() API)
+const ALL_USER_SCRIPTS = [
+ 'USER_SCRIPT', // after
+ 'ASYNC_USER_SCRIPT', // after
+ 'HEAD_SCRIPT', // in
+ 'HEAD_ASYNC_SCRIPT', // in
+ 'BEFORE_SCRIPTS_SCRIPT', // before
+ 'BEFORE_SCRIPTS_ASYNC_SCRIPT', // before
+] as const
+
+test.describe('User-rendered scripts in __root.tsx', () => {
+ test('should not cause hydration errors on SSR load', async ({ page }) => {
+ const consoleErrors: Array = []
+ page.on('console', (m) => {
+ if (m.type() === 'error') {
+ consoleErrors.push(m.text())
+ }
+ })
+
+ await page.goto('/')
+
+ // All user-rendered scripts should have executed
+ for (const scriptVar of ALL_USER_SCRIPTS) {
+ await page.waitForFunction(
+ (v) => (window as any)[v] === true,
+ scriptVar,
+ { timeout: 5000 },
+ )
+ }
+
+ // Assert no hydration errors occurred
+ const hydrationErrors = consoleErrors.filter(
+ (e) =>
+ e.includes('Hydration') ||
+ e.includes('hydration') ||
+ e.includes("didn't match"),
+ )
+ expect(hydrationErrors).toEqual([])
+ })
+
+ test('should execute on client-side navigation to another route', async ({
+ page,
+ }) => {
+ await page.goto('/posts')
+
+ await page.getByRole('link', { name: 'Home' }).click()
+ await expect(page.getByText('Welcome Home!!!')).toBeInViewport()
+
+ // Root layout scripts should have executed during the initial page load
+ for (const scriptVar of ALL_USER_SCRIPTS) {
+ await page.waitForFunction(
+ (v) => (window as any)[v] === true,
+ scriptVar,
+ { timeout: 5000 },
+ )
+ }
+ })
+})
diff --git a/e2e/react-start/basic/tests/script-duplication.spec.ts b/e2e/react-start/basic/tests/script-duplication.spec.ts
index 46e3bff00b3..b081437de87 100644
--- a/e2e/react-start/basic/tests/script-duplication.spec.ts
+++ b/e2e/react-start/basic/tests/script-duplication.spec.ts
@@ -1,35 +1,16 @@
-import { expect, test } from '@playwright/test'
+import { expect } from '@playwright/test'
+import { test } from '@tanstack/router-e2e-utils'
test.describe('Async Script Hydration', () => {
test('should not show hydration warning for async scripts', async ({
page,
}) => {
- const warnings: Array = []
- page.on('console', (msg) => {
- if (
- msg.type() === 'warning' ||
- (msg.type() === 'error' &&
- msg.text().toLowerCase().includes('hydration'))
- ) {
- warnings.push(msg.text())
- }
- })
-
await page.goto('/async-scripts')
await expect(
page.getByTestId('async-scripts-test-heading'),
).toBeInViewport()
await page.waitForFunction(() => (window as any).SCRIPT_1 === true)
-
- // Filter for hydration-related warnings
- const hydrationWarnings = warnings.filter(
- (w) =>
- w.toLowerCase().includes('hydration') ||
- w.toLowerCase().includes('mismatch'),
- )
-
- expect(hydrationWarnings).toHaveLength(0)
})
test('should load async and defer scripts correctly', async ({ page }) => {
@@ -51,11 +32,17 @@ test.describe('Script Duplication Prevention', () => {
await expect(page.getByTestId('scripts-test-heading')).toBeInViewport()
+ // Wait for the script to execute — React 19 hoists
- )
+ return null
}
- if (attrs?.src && typeof attrs.src === 'string') {
- return
- }
+ // --- Client rendering ---
- if (typeof children === 'string') {
+ // Data scripts (e.g. application/ld+json) are rendered in the tree;
+ // the useEffect intentionally skips them.
+ if (dataScript && typeof children === 'string') {
return (
)
}
+ // During hydration (before useEffect has fired), render the script element
+ // to match the server-rendered HTML and avoid structural hydration mismatches.
+ // After hydration, return null — the useEffect handles imperative injection.
+ if (!hydrated) {
+ if (attrs?.src) {
+ return
+ }
+ if (typeof children === 'string') {
+ return (
+
+ )
+ }
+ }
+
return null
}
diff --git a/packages/react-router/tests/Scripts.test.tsx b/packages/react-router/tests/Scripts.test.tsx
index e930b1dc1f8..a3f31a3a8af 100644
--- a/packages/react-router/tests/Scripts.test.tsx
+++ b/packages/react-router/tests/Scripts.test.tsx
@@ -175,7 +175,7 @@ describe('scripts with async/defer attributes', () => {
expect(html).toMatch(/]*src="script2\.js"[^>]*defer=""/)
})
- test('client renders scripts without async/defer on placeholder', async () => {
+ test('client renders scripts with attributes (including async/defer)', async () => {
const rootRoute = createRootRoute({
scripts: () => [
{
@@ -203,6 +203,10 @@ describe('scripts with async/defer attributes', () => {
},
})
+ // Clear head and any leftover body scripts between tests.
+ document.head.innerHTML = ''
+ document.querySelectorAll('body script').forEach((s) => s.remove())
+
const router = createRouter({
history: createMemoryHistory({
initialEntries: ['/'],
@@ -213,22 +217,17 @@ describe('scripts with async/defer attributes', () => {
await router.load()
- const { container } = await act(() =>
- render(),
- )
+ await act(() => render())
expect(await screen.findByTestId('async-root')).toBeInTheDocument()
- const script = container.querySelector('script')
+ const script = document.querySelector('script[src="script.js"]')
expect(script).toBeTruthy()
- // async and defer should NOT be on the client placeholder
- expect(script?.hasAttribute('async')).toBe(false)
- expect(script?.hasAttribute('defer')).toBe(false)
-
+ // Attributes are preserved on the client.
+ expect(script?.getAttribute('src')).toBe('script.js')
+ expect(script?.hasAttribute('async')).toBe(true)
expect(script?.getAttribute('crossorigin')).toBe('anonymous')
-
- expect(script?.hasAttribute('src')).toBe(false)
})
})
@@ -432,7 +431,7 @@ describe('data script rendering', () => {
expect(scriptEl!.innerHTML).toBe(jsonLd)
})
- test('executable script still renders empty on client', async () => {
+ test('executable script is injected into document.head via useEffect on client', async () => {
const rootRoute = createRootRoute({
scripts: () => [
{
@@ -471,14 +470,16 @@ describe('data script rendering', () => {
const rootEl = container.querySelector('[data-testid="exec-root"]')
expect(rootEl).not.toBeNull()
- const scripts = container.querySelectorAll('script:not([type])')
- const inlineScript = Array.from(scripts).find((s) => !s.hasAttribute('src'))
- expect(inlineScript).not.toBeNull()
- // Executable scripts should render empty (content applied via useEffect)
- expect(inlineScript!.innerHTML).toBe('')
+ // Executable inline scripts are injected into document.head via useEffect,
+ // not rendered in the React tree on the client.
+ const headScript = document.head.querySelector(
+ 'script:not([type]):not([src])',
+ )
+ expect(headScript).not.toBeNull()
+ expect(headScript!.textContent).toBe('console.log("hello")')
})
- test('module script still renders empty on client', async () => {
+ test('module script is injected into document.head via useEffect on client', async () => {
const rootRoute = createRootRoute({
scripts: () => [
{
@@ -518,10 +519,11 @@ describe('data script rendering', () => {
const rootEl = container.querySelector('[data-testid="module-root"]')
expect(rootEl).not.toBeNull()
- const moduleScript = container.querySelector('script[type="module"]')
+ // Module scripts are injected into document.head via useEffect,
+ // not rendered in the React tree on the client.
+ const moduleScript = document.head.querySelector('script[type="module"]')
expect(moduleScript).not.toBeNull()
- // Module scripts should render empty (content applied via useEffect)
- expect(moduleScript!.innerHTML).toBe('')
+ expect(moduleScript!.textContent).toBe('import { foo } from "./foo.js"')
})
test('application/json data script preserves content', async () => {
@@ -631,7 +633,7 @@ describe('data script rendering', () => {
expect(containerScripts[0]!.innerHTML).toBe(jsonLd)
})
- test('empty string type is treated as executable, not data script', async () => {
+ test('empty string type is treated as executable, injected via useEffect on client', async () => {
const rootRoute = createRootRoute({
scripts: () => [
{
@@ -671,9 +673,10 @@ describe('data script rendering', () => {
const rootEl = container.querySelector('[data-testid="empty-type-root"]')
expect(rootEl).not.toBeNull()
- const scriptEl = container.querySelector('script[type=""]')
+ // Empty type = text/javascript per HTML spec. Executable scripts are
+ // injected into document.head via useEffect on the client.
+ const scriptEl = document.head.querySelector('script[type=""]')
expect(scriptEl).not.toBeNull()
- // Empty type = text/javascript per HTML spec, should render empty like executable scripts
- expect(scriptEl!.innerHTML).toBe('')
+ expect(scriptEl!.textContent).toBe('console.log("empty type")')
})
})