fix: support usage of a prefixed a base path (#4258)

Fixes #4221

Author: SeanCassiere

e2e/react-start/custom-basepath/.gitignore

@@ -0,0 +1,20 @@
+node_modules
+package-lock.json
+yarn.lock
+
+.DS_Store
+.cache
+.env
+.vercel
+.output
+
+/build/
+/api/
+/server/build
+/public/build
+# Sentry Config File
+.env.sentry-build-plugin
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/

e2e/react-start/custom-basepath/.prettierignore

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

e2e/react-start/custom-basepath/.tanstack-start/server-routes/routeTree.gen.ts

@@ -0,0 +1,155 @@
+/* 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 Routes
+
+import type {
+  FileRoutesByPath,
+  CreateServerFileRoute,
+} from '@tanstack/react-start/server'
+import {
+  createServerRoute,
+  createServerFileRoute,
+} from '@tanstack/react-start/server'
+
+import { ServerRoute as ApiUsersRouteImport } from './../../src/routes/api.users'
+import { ServerRoute as ApiUsersIdRouteImport } from './../../src/routes/api/users.$id'
+
+// Create/Update Routes
+
+const rootRoute = createServerRoute()
+
+const ApiUsersRoute = ApiUsersRouteImport.update({
+  id: '/api/users',
+  path: '/api/users',
+  getParentRoute: () => rootRoute,
+} as any)
+
+const ApiUsersIdRoute = ApiUsersIdRouteImport.update({
+  id: '/$id',
+  path: '/$id',
+  getParentRoute: () => ApiUsersRoute,
+} as any)
+
+// Populate the FileRoutesByPath interface
+
+declare module '@tanstack/react-start/server' {
+  interface FileRoutesByPath {
+    '/api/users': {
+      id: '/api/users'
+      path: '/api/users'
+      fullPath: '/api/users'
+      preLoaderRoute: typeof ApiUsersRouteImport
+      parentRoute: typeof rootRoute
+    }
+    '/api/users/$id': {
+      id: '/api/users/$id'
+      path: '/$id'
+      fullPath: '/api/users/$id'
+      preLoaderRoute: typeof ApiUsersIdRouteImport
+      parentRoute: typeof ApiUsersRouteImport
+    }
+  }
+}
+
+// Add type-safety to the createFileRoute function across the route tree
+
+declare module './../../src/routes/api.users' {
+  const createServerFileRoute: CreateServerFileRoute<
+    FileRoutesByPath['/api/users']['parentRoute'],
+    FileRoutesByPath['/api/users']['id'],
+    FileRoutesByPath['/api/users']['path'],
+    FileRoutesByPath['/api/users']['fullPath'],
+    ApiUsersRouteChildren
+  >
+}
+declare module './../../src/routes/api/users.$id' {
+  const createServerFileRoute: CreateServerFileRoute<
+    FileRoutesByPath['/api/users/$id']['parentRoute'],
+    FileRoutesByPath['/api/users/$id']['id'],
+    FileRoutesByPath['/api/users/$id']['path'],
+    FileRoutesByPath['/api/users/$id']['fullPath'],
+    unknown
+  >
+}
+
+// Create and export the route tree
+
+interface ApiUsersRouteChildren {
+  ApiUsersIdRoute: typeof ApiUsersIdRoute
+}
+
+const ApiUsersRouteChildren: ApiUsersRouteChildren = {
+  ApiUsersIdRoute: ApiUsersIdRoute,
+}
+
+const ApiUsersRouteWithChildren = ApiUsersRoute._addFileChildren(
+  ApiUsersRouteChildren,
+)
+
+export interface FileRoutesByFullPath {
+  '/api/users': typeof ApiUsersRouteWithChildren
+  '/api/users/$id': typeof ApiUsersIdRoute
+}
+
+export interface FileRoutesByTo {
+  '/api/users': typeof ApiUsersRouteWithChildren
+  '/api/users/$id': typeof ApiUsersIdRoute
+}
+
+export interface FileRoutesById {
+  __root__: typeof rootRoute
+  '/api/users': typeof ApiUsersRouteWithChildren
+  '/api/users/$id': typeof ApiUsersIdRoute
+}
+
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths: '/api/users' | '/api/users/$id'
+  fileRoutesByTo: FileRoutesByTo
+  to: '/api/users' | '/api/users/$id'
+  id: '__root__' | '/api/users' | '/api/users/$id'
+  fileRoutesById: FileRoutesById
+}
+
+export interface RootRouteChildren {
+  ApiUsersRoute: typeof ApiUsersRouteWithChildren
+}
+
+const rootRouteChildren: RootRouteChildren = {
+  ApiUsersRoute: ApiUsersRouteWithChildren,
+}
+
+export const routeTree = rootRoute
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()
+
+/* ROUTE_MANIFEST_START
+{
+  "routes": {
+    "__root__": {
+      "filePath": "__root.tsx",
+      "children": [
+        "/api/users"
+      ]
+    },
+    "/api/users": {
+      "filePath": "api.users.ts",
+      "children": [
+        "/api/users/$id"
+      ]
+    },
+    "/api/users/$id": {
+      "filePath": "api/users.$id.ts",
+      "parent": "/api/users"
+    }
+  }
+}
+ROUTE_MANIFEST_END */

e2e/react-start/custom-basepath/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "tanstack-react-start-e2e-custom-basepath",
+  "private": true,
+  "sideEffects": false,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev --port 3000",
+    "dev:e2e": "vite dev",
+    "build": "vite build && tsc --noEmit",
+    "start": "node .output/server/index.mjs",
+    "test:e2e": "playwright test --project=chromium"
+  },
+  "dependencies": {
+    "@tanstack/react-router": "workspace:^",
+    "@tanstack/react-router-devtools": "workspace:^",
+    "@tanstack/react-start": "workspace:^",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "redaxios": "^0.5.1",
+    "tailwind-merge": "^2.6.0",
+    "vite": "6.3.5",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.50.1",
+    "@tanstack/router-e2e-utils": "workspace:^",
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "@vitejs/plugin-react": "^4.3.4",
+    "autoprefixer": "^10.4.20",
+    "combinate": "^1.1.11",
+    "postcss": "^8.5.1",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5.7.2",
+    "vite-tsconfig-paths": "^5.1.4"
+  }
+}

e2e/react-start/custom-basepath/playwright.config.ts

@@ -0,0 +1,35 @@
+import { defineConfig, devices } from '@playwright/test'
+import { derivePort } from '@tanstack/router-e2e-utils'
+import packageJson from './package.json' with { type: 'json' }
+
+const PORT = derivePort(packageJson.name)
+const baseURL = `http://localhost:${PORT}/custom/basepath`
+
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+export default defineConfig({
+  testDir: './tests',
+  workers: 1,
+
+  reporter: [['line']],
+
+  use: {
+    /* Base URL to use in actions like `await page.goto('/')`. */
+    baseURL,
+  },
+
+  webServer: {
+    command: `pnpm build && VITE_SERVER_PORT=${PORT} PORT=${PORT} pnpm start`,
+    url: baseURL,
+    reuseExistingServer: !process.env.CI,
+    stdout: 'pipe',
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+})

e2e/react-start/custom-basepath/postcss.config.mjs

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

e2e/react-start/custom-basepath/public/android-chrome-192x192.png

@@ -0,0 +1,2 @@
+console.log('SCRIPT_1 loaded')
+window.SCRIPT_1 = true

e2e/react-start/custom-basepath/public/android-chrome-512x512.png

@@ -0,0 +1,2 @@
+console.log('SCRIPT_2 loaded')
+window.SCRIPT_2 = true

e2e/react-start/custom-basepath/public/apple-touch-icon.png

@@ -0,0 +1,19 @@
+{
+  "name": "",
+  "short_name": "",
+  "icons": [
+    {
+      "src": "/android-chrome-192x192.png",
+      "sizes": "192x192",
+      "type": "image/png"
+    },
+    {
+      "src": "/android-chrome-512x512.png",
+      "sizes": "512x512",
+      "type": "image/png"
+    }
+  ],
+  "theme_color": "#ffffff",
+  "background_color": "#ffffff",
+  "display": "standalone"
+}

e2e/react-start/custom-basepath/public/favicon-16x16.png

@@ -0,0 +1,10 @@
+import * as React from 'react'
+
+export function CustomMessage({ message }: { message: string }) {
+  return (
+    <div className="py-2">
+      <div className="italic">This is a custom message:</div>
+      <p>{message}</p>
+    </div>
+  )
+}

e2e/react-start/custom-basepath/public/favicon-32x32.png

@@ -0,0 +1,53 @@
+import {
+  ErrorComponent,
+  Link,
+  rootRouteId,
+  useMatch,
+  useRouter,
+} from '@tanstack/react-router'
+import type { ErrorComponentProps } from '@tanstack/react-router'
+
+export function DefaultCatchBoundary({ error }: ErrorComponentProps) {
+  const router = useRouter()
+  const isRoot = useMatch({
+    strict: false,
+    select: (state) => state.id === rootRouteId,
+  })
+
+  console.error(error)
+
+  return (
+    <div className="min-w-0 flex-1 p-4 flex flex-col items-center justify-center gap-6">
+      <ErrorComponent error={error} />
+      <div className="flex gap-2 items-center flex-wrap">
+        <button
+          onClick={() => {
+            router.invalidate()
+          }}
+          className={`px-2 py-1 bg-gray-600 dark:bg-gray-700 rounded text-white uppercase font-extrabold`}
+        >
+          Try Again
+        </button>
+        {isRoot ? (
+          <Link
+            to="/"
+            className={`px-2 py-1 bg-gray-600 dark:bg-gray-700 rounded text-white uppercase font-extrabold`}
+          >
+            Home
+          </Link>
+        ) : (
+          <Link
+            to="/"
+            className={`px-2 py-1 bg-gray-600 dark:bg-gray-700 rounded text-white uppercase font-extrabold`}
+            onClick={(e) => {
+              e.preventDefault()
+              window.history.back()
+            }}
+          >
+            Go Back
+          </Link>
+        )}
+      </div>
+    </div>
+  )
+}

e2e/react-start/custom-basepath/public/favicon.ico

@@ -0,0 +1,25 @@
+import { Link } from '@tanstack/react-router'
+
+export function NotFound({ children }: { children?: any }) {
+  return (
+    <div className="space-y-2 p-2" data-testid="default-not-found-component">
+      <div className="text-gray-600 dark:text-gray-400">
+        {children || <p>The page you are looking for does not exist.</p>}
+      </div>
+      <p className="flex items-center gap-2 flex-wrap">
+        <button
+          onClick={() => window.history.back()}
+          className="bg-emerald-500 text-white px-2 py-1 rounded uppercase font-black text-sm"
+        >
+          Go back
+        </button>
+        <Link
+          to="/"
+          className="bg-cyan-600 text-white px-2 py-1 rounded uppercase font-black text-sm"
+        >
+          Start Over
+        </Link>
+      </p>
+    </div>
+  )
+}