fix: spa mode with prerendering (#4811)

schiller-manuel · autofix-ci[bot] · web-flow · commit d09f5daa7451 · 2025-07-28T18:56:47.000+02:00
Co-authored-by: autofix-ci[bot] &lt;114827586+autofix-ci[bot]@users.noreply.github.com&gt;
diff --git a/e2e/react-start/spa-mode/src/routes/__root.tsx b/e2e/react-start/spa-mode/src/routes/__root.tsx
@@ -9,8 +9,8 @@ import {
   createRootRoute,
   useRouterState,
 } from '@tanstack/react-router'
-import appCss from '~/styles/app.css?url'
 import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
+import appCss from '~/styles/app.css?url'
 
 export const Route = createRootRoute({
   head: () => ({
@@ -28,9 +28,6 @@ export const Route = createRootRoute({
     ],
     links: [{ rel: 'stylesheet', href: appCss }],
   }),
-  ssr: () => {
-    throw new Error('ssr() should not be called in SPA mode')
-  },
   beforeLoad: () => {
     console.log(
       `beforeLoad for ${Route.id} called on the ${typeof window !== 'undefined' ? 'client' : 'server'}`,
diff --git a/e2e/react-start/spa-mode/src/routes/index.tsx b/e2e/react-start/spa-mode/src/routes/index.tsx
@@ -1,4 +1,4 @@
-import { Link, createFileRoute, linkOptions } from '@tanstack/react-router'
+import { Link, createFileRoute } from '@tanstack/react-router'
 
 export const Route = createFileRoute('/')({
   component: Home,
diff --git a/e2e/react-start/spa-mode/src/routes/posts.$postId.tsx b/e2e/react-start/spa-mode/src/routes/posts.$postId.tsx
@@ -1,9 +1,6 @@
 import { createFileRoute } from '@tanstack/react-router'
 
 export const Route = createFileRoute('/posts/$postId')({
-  ssr: () => {
-    throw new Error('ssr() should not be called in SPA mode')
-  },
   beforeLoad: () => {
     console.log(
       `beforeLoad for ${Route.id} called on the ${typeof window !== 'undefined' ? 'client' : 'server'}`,
diff --git a/e2e/react-start/spa-mode/src/routes/posts.tsx b/e2e/react-start/spa-mode/src/routes/posts.tsx
@@ -1,9 +1,6 @@
 import { Outlet, createFileRoute } from '@tanstack/react-router'
 
 export const Route = createFileRoute('/posts')({
-  ssr: () => {
-    throw new Error('ssr() should not be called in SPA mode')
-  },
   beforeLoad: () => {
     console.log(
       `beforeLoad for ${Route.id} called on the ${typeof window !== 'undefined' ? 'client' : 'server'}`,
diff --git a/e2e/react-start/spa-mode/tests/app.spec.ts b/e2e/react-start/spa-mode/tests/app.spec.ts
@@ -1,12 +1,13 @@
-import { expect, Page } from '@playwright/test'
+import { expect } from '@playwright/test'
 import { test } from './fixture'
+import type { Page } from '@playwright/test'
 
 async function runTest(
   page: Page,
   expectedData: {
     root: 'server' | 'client'
-    posts: 'client'
-    postId: 'client'
+    posts: 'server' | 'client'
+    postId: 'server' | 'client'
   },
 ) {
   // wait for page to be loaded by waiting for the leaf route to be rendered
@@ -16,23 +17,23 @@ async function runTest(
   await Promise.all(
     Object.entries(expectedData).map(async ([route, expectedData]) => {
       await expect(page.getByTestId(`${route}-loader`)).toContainText(
-        expectedData!,
+        expectedData,
       )
       await expect(page.getByTestId(`${route}-context`)).toContainText(
-        expectedData!,
+        expectedData,
       )
     }),
   )
   await expect(page.getByTestId('router-isLoading')).toContainText('false')
   await expect(page.getByTestId('router-status')).toContainText('idle')
 }
 test.describe('SPA mode', () => {
-  test(`directly visiting /posts/1`, async ({ page }) => {
+  test(`directly visiting prerendered /posts/1`, async ({ page }) => {
     await page.goto('/posts/1')
     await runTest(page, {
       root: 'server',
-      posts: 'client',
-      postId: 'client',
+      posts: 'server',
+      postId: 'server',
     })
   })
 
diff --git a/e2e/solid-start/spa-mode/src/routes/__root.tsx b/e2e/solid-start/spa-mode/src/routes/__root.tsx
@@ -1,16 +1,15 @@
 /// <reference types="vite/client" />
 import {
   ClientOnly,
-  HeadContent,
   Link,
   Outlet,
   Scripts,
   createRootRoute,
   useRouterState,
 } from '@tanstack/solid-router'
+import { TanStackRouterDevtools } from '@tanstack/solid-router-devtools'
 import type * as Solid from 'solid-js'
 import appCss from '~/styles/app.css?url'
-import { TanStackRouterDevtools } from '@tanstack/solid-router-devtools'
 
 export const Route = createRootRoute({
   head: () => ({
@@ -28,9 +27,6 @@ export const Route = createRootRoute({
     ],
     links: [{ rel: 'stylesheet', href: appCss }],
   }),
-  ssr: () => {
-    throw new Error('ssr() should not be called in SPA mode')
-  },
   beforeLoad: () => {
     console.log(
       `beforeLoad for ${Route.id} called on the ${typeof window !== 'undefined' ? 'client' : 'server'}`,
diff --git a/e2e/solid-start/spa-mode/src/routes/index.tsx b/e2e/solid-start/spa-mode/src/routes/index.tsx
@@ -1,4 +1,4 @@
-import { Link, createFileRoute, linkOptions } from '@tanstack/solid-router'
+import { Link, createFileRoute } from '@tanstack/solid-router'
 
 export const Route = createFileRoute('/')({
   component: Home,
diff --git a/e2e/solid-start/spa-mode/src/routes/posts.$postId.tsx b/e2e/solid-start/spa-mode/src/routes/posts.$postId.tsx
@@ -1,9 +1,6 @@
 import { createFileRoute } from '@tanstack/solid-router'
 
 export const Route = createFileRoute('/posts/$postId')({
-  ssr: () => {
-    throw new Error('ssr() should not be called in SPA mode')
-  },
   beforeLoad: () => {
     console.log(
       `beforeLoad for ${Route.id} called on the ${typeof window !== 'undefined' ? 'client' : 'server'}`,
diff --git a/e2e/solid-start/spa-mode/src/routes/posts.tsx b/e2e/solid-start/spa-mode/src/routes/posts.tsx
@@ -1,9 +1,6 @@
 import { Outlet, createFileRoute } from '@tanstack/solid-router'
 
 export const Route = createFileRoute('/posts')({
-  ssr: () => {
-    throw new Error('ssr() should not be called in SPA mode')
-  },
   beforeLoad: () => {
     console.log(
       `beforeLoad for ${Route.id} called on the ${typeof window !== 'undefined' ? 'client' : 'server'}`,
diff --git a/e2e/solid-start/spa-mode/tests/app.spec.ts b/e2e/solid-start/spa-mode/tests/app.spec.ts
@@ -1,12 +1,13 @@
-import { expect, Page } from '@playwright/test'
+import { expect } from '@playwright/test'
 import { test } from './fixture'
+import type { Page } from '@playwright/test'
 
 async function runTest(
   page: Page,
   expectedData: {
     root: 'server' | 'client'
-    posts: 'client'
-    postId: 'client'
+    posts: 'server' | 'client'
+    postId: 'server' | 'client'
   },
 ) {
   // wait for page to be loaded by waiting for the leaf route to be rendered
@@ -16,23 +17,23 @@ async function runTest(
   await Promise.all(
     Object.entries(expectedData).map(async ([route, expectedData]) => {
       await expect(page.getByTestId(`${route}-loader`)).toContainText(
-        expectedData!,
+        expectedData,
       )
       await expect(page.getByTestId(`${route}-context`)).toContainText(
-        expectedData!,
+        expectedData,
       )
     }),
   )
   await expect(page.getByTestId('router-isLoading')).toContainText('false')
   await expect(page.getByTestId('router-status')).toContainText('idle')
 }
 test.describe('SPA mode', () => {
-  test(`directly visiting /posts/1`, async ({ page }) => {
+  test(`directly visiting prerendered /posts/1`, async ({ page }) => {
     await page.goto('/posts/1')
     await runTest(page, {
       root: 'server',
-      posts: 'client',
-      postId: 'client',
+      posts: 'server',
+      postId: 'server',
     })
   })
 
diff --git a/packages/start-plugin-core/src/nitro-plugin/plugin.ts b/packages/start-plugin-core/src/nitro-plugin/plugin.ts
@@ -2,6 +2,7 @@ import path from 'node:path'
 import { rmSync } from 'node:fs'
 import { build, copyPublicAssets, createNitro, prepare } from 'nitropack'
 import { dirname, resolve } from 'pathe'
+import { HEADERS } from '@tanstack/start-server-core'
 import {
   CLIENT_DIST_DIR,
   SSR_ENTRY_FILE,
@@ -157,9 +158,9 @@ async function buildNitroApp(
       path: maskUrl.toString().replace('http://localhost', ''),
       prerender: {
         ...options.spa.prerender,
-        env: {
-          ...options.spa.prerender.env,
-          TSS_SPA_MODE: 'true',
+        headers: {
+          ...options.spa.prerender.headers,
+          [HEADERS.TSS_SHELL]: 'true',
         },
       },
       sitemap: {
diff --git a/packages/start-plugin-core/src/nitro-plugin/prerender.ts b/packages/start-plugin-core/src/nitro-plugin/prerender.ts
@@ -89,6 +89,8 @@ export async function prerender({
     path.resolve(path.join(nodeNitro.options.output.serverDir, serverFilename)),
   ).toString()
 
+  process.env.TSS_PRERENDERING = 'true'
+
   const { closePrerenderer, localFetch } = (await import(serverEntrypoint)) as {
     closePrerenderer: () => void
     localFetch: $Fetch
@@ -171,13 +173,6 @@ export async function prerender({
           // Fetch the route
           const encodedRoute = encodeURI(page.path)
 
-          const originalEnv = { ...process.env }
-
-          process.env = {
-            ...originalEnv,
-            TSS_PRERENDERING: 'true',
-            ...(prerenderOptions.env || {}),
-          }
           const res = await localFetch<Response>(
             withBase(encodedRoute, nodeNitro.options.baseURL),
             {
@@ -187,7 +182,7 @@ export async function prerender({
               },
             },
           )
-          process.env = originalEnv
+
           if (!res.ok) {
             throw new Error(`Failed to fetch ${page.path}: ${res.statusText}`, {
               cause: res,
diff --git a/packages/start-plugin-core/src/plugin.ts b/packages/start-plugin-core/src/plugin.ts
@@ -147,7 +147,7 @@ export function TanStackStartVitePluginCore(
             ...defineReplaceEnv('TSS_SERVER_FN_BASE', startConfig.serverFns.base),
             ...defineReplaceEnv('TSS_OUTPUT_PUBLIC_DIR', nitroOutputPublicDir),
             ...defineReplaceEnv('TSS_APP_BASE', viteAppBase),
-            ...(command === 'serve' ? defineReplaceEnv('TSS_SPA_MODE', startConfig.spa?.enabled ? 'true' : 'false') : {}),
+            ...(command === 'serve' ? defineReplaceEnv('TSS_SHELL', startConfig.spa?.enabled ? 'true' : 'false') : {}),
           },
         }
       },
diff --git a/packages/start-plugin-core/src/schema.ts b/packages/start-plugin-core/src/schema.ts
@@ -197,7 +197,6 @@ const pagePrerenderOptionsSchema = z.object({
     .returns(z.any())
     .optional(),
   headers: z.record(z.string(), z.string()).optional(),
-  env: z.record(z.string(), z.string()).optional(),
 })
 
 const spaSchema = z.object({
diff --git a/packages/start-server-core/src/constants.ts b/packages/start-server-core/src/constants.ts
@@ -0,0 +1,3 @@
+export const HEADERS = {
+  TSS_SHELL: 'X-TSS_SHELL',
+} as const
diff --git a/packages/start-server-core/src/createStartHandler.ts b/packages/start-server-core/src/createStartHandler.ts
@@ -20,6 +20,7 @@ import { handleServerAction } from './server-functions-handler'
 import { VIRTUAL_MODULES } from './virtual-modules'
 import { loadVirtualModule } from './loadVirtualModule'
 
+import { HEADERS } from './constants'
 import type {
   AnyServerRouteWithTypes,
   ServerRouteMethodHandlerFn,
@@ -123,10 +124,19 @@ export function createStartHandler<TRouter extends AnyRouter>({
       })
 
       // Update the client-side router with the history
+      const isPrerendering = process.env.TSS_PRERENDERING === 'true'
+      // env var is set during dev is SPA mode is enabled
+      let isShell = process.env.TSS_SHELL === 'true'
+      if (isPrerendering && !isShell) {
+        // only read the shell header if we are prerendering
+        // to avoid runtime behavior changes by injecting this header
+        // the header is set by the prerender plugin
+        isShell = request.headers.get(HEADERS.TSS_SHELL) === 'true'
+      }
       router.update({
         history,
-        isShell: process.env.TSS_SPA_MODE === 'true',
-        isPrerendering: process.env.TSS_PRERENDERING === 'true',
+        isShell,
+        isPrerendering,
       })
 
       const response = await (async () => {
diff --git a/packages/start-server-core/src/global.d.ts b/packages/start-server-core/src/global.d.ts
@@ -1,6 +1,16 @@
+/* eslint-disable no-var */
 declare global {
-  // eslint-disable-next-line no-var
   var TSS_INJECTED_HEAD_SCRIPTS: string | undefined
+
+  namespace NodeJS {
+    interface ProcessEnv {
+      TSS_APP_BASE?: string
+      TSS_SERVER_FN_BASE?: string
+      TSS_OUTPUT_PUBLIC_DIR?: string
+      TSS_SHELL?: 'true' | 'false'
+      TSS_PRERENDERING?: 'true' | 'false'
+    }
+  }
 }
 
 export {}
diff --git a/packages/start-server-core/src/index.tsx b/packages/start-server-core/src/index.tsx
@@ -56,3 +56,5 @@ export type {
 } from './serverRoute'
 
 export * from './virtual-modules'
+
+export { HEADERS } from './constants'

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import { Link, createFileRoute, linkOptions } from '@tanstack/react-router'`
	`1`	`+import { Link, createFileRoute } from '@tanstack/react-router'`
`2`	`2`
`3`	`3`	`export const Route = createFileRoute('/')({`
`4`	`4`	`component: Home,`