feat: support split base and basepath in TanStack Start dev server

e2e/react-start/import-protection/vite.config.ts

@@ -26,12 +26,6 @@ export default defineConfig({
       },
     }),
   ],
-  // Keep the unused import from being tree-shaken in older TS configs
-  define: {
-    __IMPORT_PROTECTION_FIXTURE_ROOT__: JSON.stringify(
-      path.resolve(import.meta.dirname),
-    ),
-  },
   // react-tweet's package.json exports resolve to `index.client.js` which
   // matches the default **/*.client.* deny pattern.  Bundling it via
   // noExternal must NOT trigger a false-positive import-protection violation.

e2e/react-start/split-base-and-basepath/.gitignore

@@ -0,0 +1,18 @@
+node_modules
+package-lock.json
+yarn.lock
+
+.DS_Store
+.cache
+.env
+.vercel
+.output
+
+/build/
+/api/
+/server/build
+/public/build
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/

e2e/react-start/split-base-and-basepath/.prettierignore

@@ -0,0 +1,4 @@
+**/build
+**/public
+pnpm-lock.yaml
+routeTree.gen.ts

e2e/react-start/split-base-and-basepath/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "tanstack-react-start-e2e-split-base-and-basepath",
+  "private": true,
+  "sideEffects": false,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev --port 3000",
+    "dev:e2e": "vite dev --port $PORT",
+    "build": "vite build && tsc --noEmit",
+    "start": "node prod-server.js",
+    "test:e2e:dev": "MODE=dev playwright test --project=chromium",
+    "test:e2e:prod": "playwright test --project=chromium",
+    "test:e2e": "rm -rf port*.txt; pnpm run test:e2e:dev && pnpm run test:e2e:prod"
+  },
+  "dependencies": {
+    "@tanstack/react-router": "workspace:^",
+    "@tanstack/react-start": "workspace:^",
+    "express": "^4.21.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.50.1",
+    "@tanstack/router-e2e-utils": "workspace:^",
+    "@types/express": "^5.0.3",
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "@vitejs/plugin-react": "^4.3.4",
+    "srvx": "^0.11.7",
+    "typescript": "^5.7.2",
+    "vite": "^7.3.1",
+    "vite-tsconfig-paths": "^5.1.4"
+  }
+}

e2e/react-start/split-base-and-basepath/playwright.config.ts

@@ -0,0 +1,38 @@
+import { defineConfig, devices } from '@playwright/test'
+import { getTestServerPort } from '@tanstack/router-e2e-utils'
+import packageJson from './package.json' with { type: 'json' }
+
+const mode = process.env.MODE ?? 'prod'
+const isDev = mode === 'dev'
+
+const PORT = await getTestServerPort(packageJson.name)
+const baseURL = `http://localhost:${PORT}`
+
+export default defineConfig({
+  testDir: './tests',
+  workers: 1,
+  reporter: [['line']],
+
+  use: {
+    baseURL,
+  },
+
+  webServer: {
+    command: isDev ? `pnpm dev:e2e` : `pnpm build && PORT=${PORT} pnpm start`,
+    url: baseURL,
+    reuseExistingServer: !process.env.CI,
+    stdout: 'pipe',
+    env: {
+      PORT: String(PORT),
+    },
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: {
+        ...devices['Desktop Chrome'],
+      },
+    },
+  ],
+})

e2e/react-start/split-base-and-basepath/prod-server.js

@@ -0,0 +1,25 @@
+import express from 'express'
+import { toNodeHandler } from 'srvx/node'
+
+const PORT = Number.parseInt(process.env.PORT || '3000')
+
+const app = express()
+
+const { default: handler } = await import('./dist/server/server.js')
+const nodeHandler = toNodeHandler(handler.fetch)
+
+// Serve built client assets at /_ui/ prefix
+app.use('/_ui', express.static('dist/client'))
+
+// All other requests go through the SSR handler
+app.use(async (req, res, next) => {
+  try {
+    await nodeHandler(req, res)
+  } catch (error) {
+    next(error)
+  }
+})
+
+app.listen(PORT, () => {
+  console.log(`Server is running on http://localhost:${PORT}`)
+})

e2e/react-start/split-base-and-basepath/src/routeTree.gen.ts

@@ -0,0 +1,86 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as AboutRouteImport } from './routes/about'
+import { Route as IndexRouteImport } from './routes/index'
+
+const AboutRoute = AboutRouteImport.update({
+  id: '/about',
+  path: '/about',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+  '/about': typeof AboutRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+  '/about': typeof AboutRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+  '/about': typeof AboutRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths: '/' | '/about'
+  fileRoutesByTo: FileRoutesByTo
+  to: '/' | '/about'
+  id: '__root__' | '/' | '/about'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+  AboutRoute: typeof AboutRoute
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/about': {
+      id: '/about'
+      path: '/about'
+      fullPath: '/about'
+      preLoaderRoute: typeof AboutRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+  }
+}
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+  AboutRoute: AboutRoute,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()
+
+import type { getRouter } from './router.tsx'
+import type { createStart } from '@tanstack/react-start'
+declare module '@tanstack/react-start' {
+  interface Register {
+    ssr: true
+    router: Awaited<ReturnType<typeof getRouter>>
+  }
+}

e2e/react-start/split-base-and-basepath/src/router.tsx

@@ -0,0 +1,12 @@
+import { createRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+
+export function getRouter() {
+  const router = createRouter({
+    routeTree,
+    scrollRestoration: true,
+    defaultPreload: 'intent',
+  })
+
+  return router
+}

e2e/react-start/split-base-and-basepath/src/routes/__root.tsx

@@ -0,0 +1,53 @@
+/// <reference types="vite/client" />
+import {
+  HeadContent,
+  Link,
+  Outlet,
+  Scripts,
+  createRootRoute,
+} from '@tanstack/react-router'
+
+import appCss from '~/styles/app.css?url'
+
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      { charSet: 'utf-8' },
+      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
+    ],
+    links: [{ rel: 'stylesheet', href: appCss }],
+  }),
+  component: RootComponent,
+})
+
+function RootComponent() {
+  return (
+    <html>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <nav>
+          <Link
+            to="/"
+            activeProps={{ className: 'active' }}
+            activeOptions={{ exact: true }}
+            data-testid="link-home"
+          >
+            Home
+          </Link>{' '}
+          <Link
+            to="/about"
+            activeProps={{ className: 'active' }}
+            data-testid="link-about"
+          >
+            About
+          </Link>
+        </nav>
+        <hr />
+        <Outlet />
+        <Scripts />
+      </body>
+    </html>
+  )
+}

e2e/react-start/split-base-and-basepath/src/routes/about.tsx

@@ -0,0 +1,14 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/about')({
+  component: About,
+})
+
+function About() {
+  return (
+    <div>
+      <h1 data-testid="about-heading">About Page</h1>
+      <p data-testid="about-content">This is the about page.</p>
+    </div>
+  )
+}

e2e/react-start/split-base-and-basepath/src/routes/index.tsx

@@ -0,0 +1,16 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/')({
+  component: Home,
+})
+
+function Home() {
+  return (
+    <div>
+      <h1 data-testid="home-heading">Welcome Home</h1>
+      <p data-testid="home-content">
+        This page tests that split base and basepath work correctly.
+      </p>
+    </div>
+  )
+}

e2e/react-start/split-base-and-basepath/src/styles/app.css

@@ -0,0 +1,20 @@
+body {
+  font-family: sans-serif;
+  margin: 0;
+  padding: 16px;
+}
+
+.app-styled {
+  color: #333;
+  background-color: #f0f0f0;
+}
+
+nav {
+  display: flex;
+  gap: 8px;
+  font-size: 1.1rem;
+}
+
+nav a.active {
+  font-weight: bold;
+}