Merge branch 'main' into main

Author: schiller-manuel

docs/router/framework/react/api/router/NotFoundErrorType.md

@@ -37,7 +37,7 @@ The `NotFoundError` object accepts/contains the following properties:
 - Optional - `default: false`
 - If provided, will throw the not-found object instead of returning it. This can be useful in places where `throwing` in a function might cause it to have a return type of `never`. In that case, you can use `notFound({ throw: true })` to throw the not-found object instead of returning it.
 
-### `route` property
+### `routeId` property
 
 - Type: `string`
 - Optional

docs/router/framework/react/api/router/linkComponent.md

@@ -35,3 +35,21 @@ function Component() {
   )
 }
 ```
+
+By default, param values with characters such as `@` will be encoded in the URL:
+
+```tsx
+// url path will be `/%40foo`
+<Link to="/$username" params={{ username: '@foo' }} />
+```
+
+To opt-out, update the [pathParamsAllowedCharacters](../router/RouterOptionsType#pathparamsallowedcharacters-property) config on the router
+
+```tsx
+import { createRouter } from '@tanstack/react-router'
+
+const router = createRouter({
+  routeTree,
+  pathParamsAllowedCharacters: ['@'],
+})
+```

docs/router/framework/react/guide/document-head-management.md

@@ -89,7 +89,7 @@ export const Route = createRootRoute({
 
 ### Single-Page Applications
 
-First, remove the `<title>` tag from the the index.html if you have set any.
+First, remove the `<title>` tag from the index.html if you have set any.
 
 ```tsx
 import { HeadContent } from '@tanstack/react-router'

docs/router/framework/react/guide/internationalization-i18n.md

@@ -25,8 +25,8 @@ This pattern relies exclusively on TanStack Router features. It is suitable when
 
 Optional path parameters are ideal for implementing locale-aware routing without duplicating routes.
 
-```ts
-;/{-$locale}/abotu
+```
+/{-$locale}/about
 ```
 
 This single route matches:

docs/router/framework/react/how-to/setup-ssr.md

@@ -142,7 +142,7 @@ hydrateRoot(document, <RouterClient router={router} />)
 // vite.config.ts
 import path from 'node:path'
 import url from 'node:url'
-import { TanStackRouterVite } from '@tanstack/router-plugin/vite'
+import { tanstackRouter } from '@tanstack/router-plugin/vite'
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 
@@ -151,7 +151,7 @@ const __dirname = path.dirname(__filename)
 
 export default defineConfig(({ isSsrBuild }) => ({
   plugins: [
-    TanStackRouterVite({
+    tanstackRouter({
       autoCodeSplitting: true,
     }),
     react(),
@@ -407,7 +407,7 @@ For streaming SSR, update your Vite config:
 // vite.config.ts
 export default defineConfig(({ isSsrBuild }) => ({
   plugins: [
-    TanStackRouterVite({
+    tanstackRouter({
       autoCodeSplitting: true,
       enableStreaming: true, // Enable streaming support
     }),

docs/router/framework/react/how-to/test-file-based-routing.md

@@ -38,11 +38,11 @@ Create `vitest.config.ts` with file-based routing support:
 ```ts
 import { defineConfig } from 'vitest/config'
 import react from '@vitejs/plugin-react'
-import { TanStackRouterVite } from '@tanstack/router-plugin/vite'
+import { tanstackRouter } from '@tanstack/router-plugin/vite'
 
 export default defineConfig({
   plugins: [
-    TanStackRouterVite({
+    tanstackRouter({
       // Configure for test environment
       routesDirectory: './src/routes',
       generatedRouteTree: './src/routeTree.gen.ts',
@@ -898,7 +898,7 @@ Error: Cannot find module '../routeTree.gen'
 // vitest.config.ts
 export default defineConfig({
   plugins: [
-    TanStackRouterVite(), // Ensure this runs before tests
+    tanstackRouter(), // Ensure this runs before tests
     react(),
   ],
   test: {

docs/router/framework/react/how-to/use-environment-variables.md

@@ -436,13 +436,13 @@ export const Route = createFileRoute('/api-data')({
 // vite.config.ts
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
-import { TanStackRouterVite } from '@tanstack/router-vite-plugin'
+import { tanstackRouter } from '@tanstack/router-plugin/vite'
 
 export default defineConfig({
   plugins: [
     react(),
-    // TanStackRouterVite generates route tree and enables file-based routing
-    TanStackRouterVite(),
+    // tanstackRouter generates route tree and enables file-based routing
+    tanstackRouter(),
   ],
   // Environment variables are handled automatically
   // Custom environment variable handling:

docs/start/config.json

@@ -137,6 +137,10 @@
               "label": "Server Entry Point",
               "to": "framework/react/guide/server-entry-point"
             },
+            {
+              "label": "CDN Asset URLs",
+              "to": "framework/react/guide/cdn-asset-urls"
+            },
             {
               "label": "Client Entry Point",
               "to": "framework/react/guide/client-entry-point"

docs/start/framework/react/getting-started.md

@@ -15,7 +15,7 @@ title: Getting Started
 Choose one of the following options to start building a _new_ TanStack Start project:
 
 - [TanStack Start CLI](./quick-start) - Just run `npm create @tanstack/start@latest`. Local, fast, and optionally customizable
-- [TanStack Builder](#) (coming soon!) - A visual interface to configure new TanStack projects with a few clicks
+- [TanStack Builder](https://tanstack.com/builder) - A visual interface to configure new TanStack projects with a few clicks
 - [Quick Start Examples](./quick-start) Download or clone one of our official examples
 - [Build a project from scratch](./build-from-scratch) - A guide to building a TanStack Start project line-by-line, file-by-file.
 

docs/start/framework/react/guide/cdn-asset-urls.md

@@ -0,0 +1,224 @@
+---
+id: cdn-asset-urls
+title: CDN Asset URLs
+---
+
+# CDN Asset URLs
+
+> **Experimental:** `transformAssetUrls` is experimental and subject to change.
+
+When deploying to production, you may want to serve your static assets (JavaScript, CSS) from a CDN. The `transformAssetUrls` option on `createStartHandler` lets you rewrite asset URLs at runtime — for example, prepending a CDN origin that is only known when the server starts.
+
+## Why Runtime URL Rewriting?
+
+Vite's `base` config is evaluated at build time. If your CDN URL is determined at deploy time (via environment variables, dynamic configuration, etc.), you need a way to rewrite URLs at runtime. `transformAssetUrls` solves this for the URLs that TanStack Start manages in its manifest:
+
+- `<link rel="modulepreload">` tags (JS preloads)
+- `<link rel="stylesheet">` tags (CSS)
+- The client entry `<script>` tag
+
+## Basic Usage
+
+### String Prefix
+
+The simplest usage is passing a string. Every manifest asset URL will be prefixed with it:
+
+```tsx
+// src/server.ts
+import {
+  createStartHandler,
+  defaultStreamHandler,
+} from '@tanstack/react-start/server'
+import { createServerEntry } from '@tanstack/react-start/server-entry'
+
+const handler = createStartHandler({
+  handler: defaultStreamHandler,
+  transformAssetUrls: process.env.CDN_ORIGIN || '',
+})
+
+export default createServerEntry({ fetch: handler })
+```
+
+If `CDN_ORIGIN` is `https://cdn.example.com` and an asset URL is `/assets/index-abc123.js`, the resulting URL will be `https://cdn.example.com/assets/index-abc123.js`.
+
+When the string is empty (or not set), the URLs are left unchanged.
+
+### Callback
+
+For more control, pass a callback that receives `{ url, type }` and returns a new URL (or a `Promise` of one). By default, the transformed manifest is cached after the first request (`cache: true`), so the callback only runs once in production:
+
+```tsx
+// src/server.ts
+import {
+  createStartHandler,
+  defaultStreamHandler,
+} from '@tanstack/react-start/server'
+import { createServerEntry } from '@tanstack/react-start/server-entry'
+
+const handler = createStartHandler({
+  handler: defaultStreamHandler,
+  transformAssetUrls: ({ url, type }) => {
+    // Only rewrite JS and CSS, leave client entry unchanged
+    if (type === 'clientEntry') return url
+    return `https://cdn.example.com${url}`
+  },
+})
+
+export default createServerEntry({ fetch: handler })
+```
+
+If you need per-request behavior (for example, choosing a CDN based on a header), use the object form with `cache: false`.
+
+The `type` parameter tells you what kind of asset URL is being transformed:
+
+| `type`            | Description                                          |
+| ----------------- | ---------------------------------------------------- |
+| `'modulepreload'` | JS module preload URL (`<link rel="modulepreload">`) |
+| `'stylesheet'`    | CSS stylesheet URL (`<link rel="stylesheet">`)       |
+| `'clientEntry'`   | Client entry module URL (used in `import('...')`)    |
+
+### Object Form (Explicit Cache Control)
+
+For per-request transforms — where the CDN URL depends on request-specific data like headers — use the object form with `cache: false`:
+
+```tsx
+// src/server.ts
+import {
+  createStartHandler,
+  defaultStreamHandler,
+} from '@tanstack/react-start/server'
+import { createServerEntry } from '@tanstack/react-start/server-entry'
+import { getRequest } from '@tanstack/react-start/server'
+
+const handler = createStartHandler({
+  handler: defaultStreamHandler,
+  transformAssetUrls: {
+    transform: ({ url, type }) => {
+      const region = getRequest().headers.get('x-region') || 'us'
+      const cdnBase =
+        region === 'eu'
+          ? 'https://cdn-eu.example.com'
+          : 'https://cdn-us.example.com'
+      return `${cdnBase}${url}`
+    },
+    cache: false,
+  },
+})
+
+export default createServerEntry({ fetch: handler })
+```
+
+The object form accepts:
+
+| Property          | Type                                                                                                     | Description                                                                                                                   |
+| ----------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `transform`       | `string \| (asset) => string \| Promise<string>`                                                         | A string prefix or callback, same as the shorthand forms above.                                                               |
+| `createTransform` | `(ctx: { warmup: true } \| { warmup: false; request: Request }) => (asset) => string \| Promise<string>` | Async factory that runs once per manifest computation and returns a per-asset transform. Mutually exclusive with `transform`. |
+| `cache`           | `boolean`                                                                                                | Whether to cache the transformed manifest. Defaults to `true`.                                                                |
+| `warmup`          | `boolean`                                                                                                | When `true`, warms up the cached manifest on server startup (prod only). Defaults to `false`.                                 |
+
+If you need to do async work once per manifest computation (e.g. fetch a CDN origin from a service) and then transform many URLs, prefer `createTransform`:
+
+```ts
+transformAssetUrls: {
+  cache: false,
+  async createTransform(ctx) {
+    if (ctx.warmup) {
+      // optional: return a default transform during warmup
+      return ({ url }) => url
+    }
+
+    const region = ctx.request.headers.get('x-region') || 'us'
+    const cdnBase = await fetchCdnBaseForRegion(region)
+    return ({ url }) => `${cdnBase}${url}`
+  },
+}
+```
+
+## Caching Behavior
+
+By default, **all forms** of `transformAssetUrls` cache the transformed manifest after the first request (`cache: true`). This means the transform function runs once on the first request, and the result is reused for every subsequent request in production.
+
+| Form                                   | Default cache | Behavior                                                   |
+| -------------------------------------- | ------------- | ---------------------------------------------------------- |
+| String prefix                          | `true`        | Computed once, cached forever in prod.                     |
+| Callback                               | `true`        | Runs once on first request, cached forever in prod.        |
+| Object with `cache: true` (or omitted) | `true`        | Same as above.                                             |
+| Object with `cache: false`             | `false`       | Deep-clones base manifest and transforms on every request. |
+
+Use `cache: false` only when the transform depends on per-request data (e.g., geo-routing based on request headers). For static CDN prefixes, the default `cache: true` is recommended.
+
+### Optional Warmup (Avoid First-Request Latency)
+
+If you're using the object form with `cache: true`, you can set `warmup: true`
+to compute the transformed manifest in the background at server startup.
+
+```ts
+transformAssetUrls: {
+  transform: process.env.CDN_ORIGIN || '',
+  cache: true,
+  warmup: true,
+}
+```
+
+This has no effect in development mode, or when `cache: false`.
+
+> **Note:** In development mode (`TSS_DEV_SERVER`), caching is always skipped regardless of the `cache` setting, so you always get fresh manifests.
+
+## Recommended: Set `base: ''` for Client-Side Navigation
+
+`transformAssetUrls` rewrites the URLs in the SSR HTML — modulepreload hints, stylesheets, and the client entry script. This means the browser's initial page load fetches all assets from the CDN.
+
+However, when users navigate client-side (e.g., clicking a `<Link>`), TanStack Router lazy-loads route chunks using `import()` calls with paths that were baked in at **build time** by Vite. By default, Vite uses `base: '/'`, which produces absolute paths like `/assets/about-abc123.js`. These resolve against the **app server's origin**, not the CDN — even though the entry module was loaded from the CDN.
+
+To fix this, set `base: ''` in your Vite config:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  base: '',
+  // ... plugins, etc.
+})
+```
+
+With `base: ''`, Vite generates **relative** import paths for client-side chunks. Since the client entry module was loaded from the CDN (thanks to `transformAssetUrls`), all relative `import()` calls resolve against the CDN origin. This ensures that lazy-loaded route chunks during client-side navigation are also served from the CDN.
+
+Using an empty string rather than `'./'` is important — both produce relative client-side imports, but `base: ''` preserves the correct root-relative paths (`/assets/...`) in the SSR manifest so that `transformAssetUrls` can properly prepend the CDN origin.
+
+| `base` setting  | SSR assets (initial load)      | Client-side navigation chunks  |
+| --------------- | ------------------------------ | ------------------------------ |
+| `'/'` (default) | CDN (via `transformAssetUrls`) | App server                     |
+| `''`            | CDN (via `transformAssetUrls`) | CDN (relative to entry module) |
+
+> **Tip:** `base: ''` is recommended whenever you use `transformAssetUrls` so that all assets — both on initial load and during client-side navigation — are consistently served from the CDN.
+
+## What This Does NOT Cover
+
+`transformAssetUrls` only rewrites URLs in the TanStack Start manifest — the tags emitted during SSR for preloading and bootstrapping the application.
+
+It does **not** rewrite asset URLs that are imported directly in your components:
+
+```tsx
+// This import resolves to a URL at build time by Vite
+import logo from './logo.svg'
+
+function Header() {
+  return <img src={logo} /> // This URL is NOT affected by transformAssetUrls
+}
+```
+
+For these asset imports, use Vite's `experimental.renderBuiltUrl` in your `vite.config.ts`:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  experimental: {
+    renderBuiltUrl(filename, { hostType }) {
+      if (hostType === 'js') {
+        return { relative: true }
+      }
+      return `https://cdn.example.com/${filename}`
+    },
+  },
+})
+```