From ec92b3a4cc55e19705cf49c123fbadd35c08f984 Mon Sep 17 00:00:00 2001
From: whizzkid1452 <247364087+whizzkid1452@users.noreply.github.com>
Date: Thu, 23 Jul 2026 18:19:05 +0900
Subject: [PATCH] docs(start): document route and asset base paths

---
 docs/start/config.json                        |  8 ++
 .../start/framework/react/guide/base-paths.md | 89 +++++++++++++++++++
 .../start/framework/solid/guide/base-paths.md |  3 +
 3 files changed, 100 insertions(+)
 create mode 100644 docs/start/framework/react/guide/base-paths.md
 create mode 100644 docs/start/framework/solid/guide/base-paths.md

diff --git a/docs/start/config.json b/docs/start/config.json
index 57703aad89..c3dd16b3bc 100644
--- a/docs/start/config.json
+++ b/docs/start/config.json
@@ -70,6 +70,10 @@
               "label": "Routing",
               "to": "framework/react/guide/routing"
             },
+            {
+              "label": "Base Paths",
+              "to": "framework/react/guide/base-paths"
+            },
             {
               "label": "Execution Model",
               "to": "framework/react/guide/execution-model"
@@ -131,6 +135,10 @@
               "label": "Routing",
               "to": "framework/solid/guide/routing"
             },
+            {
+              "label": "Base Paths",
+              "to": "framework/solid/guide/base-paths"
+            },
             {
               "label": "Execution Model",
               "to": "framework/solid/guide/execution-model"
diff --git a/docs/start/framework/react/guide/base-paths.md b/docs/start/framework/react/guide/base-paths.md
new file mode 100644
index 0000000000..fa335b424a
--- /dev/null
+++ b/docs/start/framework/react/guide/base-paths.md
@@ -0,0 +1,89 @@
+---
+id: base-paths
+title: Base Paths
+---
+
+# Base Paths
+
+Use base paths when your application or its assets are served below the origin root. TanStack Start has two separate settings:
+
+- Vite's `base` controls the public URL prefix for assets, such as JavaScript and CSS.
+- Start's `router.basepath` controls the URL prefix for application routes and server functions.
+
+Configure these settings in `vite.config.ts`. Do not rely on the router instance in `src/router.tsx` to configure a Start base path.
+
+## Serve the Application and Assets from the Same Path
+
+For example, to serve the application and its assets from `/app/`, set both options to the same path:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import viteReact from '@vitejs/plugin-react'
+
+export default defineConfig({
+  base: '/app/',
+  plugins: [
+    tanstackStart({
+      router: {
+        basepath: '/app',
+      },
+    }),
+    viteReact(),
+  ],
+})
+```
+
+This configuration produces URLs with the following responsibilities:
+
+| URL                  | Prefix source                          |
+| -------------------- | -------------------------------------- |
+| `/app/about`         | `router.basepath`                      |
+| `/app/_serverFn/...` | `router.basepath` and `serverFns.base` |
+| `/app/assets/...`    | Vite `base`                            |
+
+If you omit `router.basepath`, Start derives it from a path-based Vite `base`. Setting both explicitly can make the deployment contract easier to see.
+
+Your development server handles this configuration automatically. In production, configure your server or reverse proxy to forward `/app/*` to the Start application and serve the client assets at the same prefix.
+
+## Use Different Paths for Routes and Assets
+
+You can keep application routes at the origin root while serving assets from another path. Set Vite's `base` to the asset prefix and set `router.basepath` explicitly to `/`:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import viteReact from '@vitejs/plugin-react'
+
+export default defineConfig({
+  base: '/_ui/',
+  plugins: [
+    tanstackStart({
+      router: {
+        basepath: '/',
+      },
+    }),
+    viteReact(),
+  ],
+})
+```
+
+This configuration produces application routes such as `/` and `/about`, while JavaScript and CSS URLs begin with `/_ui/`.
+
+In production, make both URL spaces available:
+
+- Forward application routes such as `/about` to the Start server.
+- Serve or forward asset requests under `/_ui/`.
+
+## Verify the Configuration
+
+Check both direct requests and client-side navigation:
+
+1. Open the application at its configured route base.
+2. Navigate with a `Link` and confirm that the route URL contains `router.basepath`, not Vite's `base`.
+3. Inspect script and stylesheet URLs and confirm that they contain Vite's `base`.
+4. Load a nested route directly to verify that the production server forwards it correctly.
+
+For runtime asset rewriting with a Content Delivery Network (CDN), see [CDN Asset URLs](./cdn-asset-urls).
diff --git a/docs/start/framework/solid/guide/base-paths.md b/docs/start/framework/solid/guide/base-paths.md
new file mode 100644
index 0000000000..22b644c19f
--- /dev/null
+++ b/docs/start/framework/solid/guide/base-paths.md
@@ -0,0 +1,3 @@
+---
+ref: docs/start/framework/react/guide/base-paths.md
+---