diff --git a/e2e/react-start/optional-params/.gitignore b/e2e/react-start/optional-params/.gitignore
new file mode 100644
index 0000000000..a79d5cf129
--- /dev/null
+++ b/e2e/react-start/optional-params/.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/
diff --git a/e2e/react-start/optional-params/package.json b/e2e/react-start/optional-params/package.json
new file mode 100644
index 0000000000..5a4fc6da86
--- /dev/null
+++ b/e2e/react-start/optional-params/package.json
@@ -0,0 +1,38 @@
+{
+ "name": "tanstack-react-start-e2e-optional-params",
+ "private": true,
+ "sideEffects": false,
+ "type": "module",
+ "scripts": {
+ "dev": "vite dev --port 3002",
+ "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"
+ }
+}
diff --git a/e2e/react-start/optional-params/playwright.config.ts b/e2e/react-start/optional-params/playwright.config.ts
new file mode 100644
index 0000000000..e834d88cf4
--- /dev/null
+++ b/e2e/react-start/optional-params/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}`
+
+/**
+ * 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'] },
+ },
+ ],
+})
diff --git a/e2e/react-start/optional-params/postcss.config.mjs b/e2e/react-start/optional-params/postcss.config.mjs
new file mode 100644
index 0000000000..2e7af2b7f1
--- /dev/null
+++ b/e2e/react-start/optional-params/postcss.config.mjs
@@ -0,0 +1,6 @@
+export default {
+ plugins: {
+ tailwindcss: {},
+ autoprefixer: {},
+ },
+}
diff --git a/e2e/react-start/optional-params/public/android-chrome-192x192.png b/e2e/react-start/optional-params/public/android-chrome-192x192.png
new file mode 100644
index 0000000000..09c8324f8c
Binary files /dev/null and b/e2e/react-start/optional-params/public/android-chrome-192x192.png differ
diff --git a/e2e/react-start/optional-params/public/android-chrome-512x512.png b/e2e/react-start/optional-params/public/android-chrome-512x512.png
new file mode 100644
index 0000000000..11d626ea3d
Binary files /dev/null and b/e2e/react-start/optional-params/public/android-chrome-512x512.png differ
diff --git a/e2e/react-start/optional-params/public/apple-touch-icon.png b/e2e/react-start/optional-params/public/apple-touch-icon.png
new file mode 100644
index 0000000000..5a9423cc02
Binary files /dev/null and b/e2e/react-start/optional-params/public/apple-touch-icon.png differ
diff --git a/e2e/react-start/optional-params/public/favicon-16x16.png b/e2e/react-start/optional-params/public/favicon-16x16.png
new file mode 100644
index 0000000000..e3389b0044
Binary files /dev/null and b/e2e/react-start/optional-params/public/favicon-16x16.png differ
diff --git a/e2e/react-start/optional-params/public/favicon-32x32.png b/e2e/react-start/optional-params/public/favicon-32x32.png
new file mode 100644
index 0000000000..900c77d444
Binary files /dev/null and b/e2e/react-start/optional-params/public/favicon-32x32.png differ
diff --git a/e2e/react-start/optional-params/public/favicon.ico b/e2e/react-start/optional-params/public/favicon.ico
new file mode 100644
index 0000000000..1a1751676f
Binary files /dev/null and b/e2e/react-start/optional-params/public/favicon.ico differ
diff --git a/e2e/react-start/optional-params/public/favicon.png b/e2e/react-start/optional-params/public/favicon.png
new file mode 100644
index 0000000000..1e77bc0609
Binary files /dev/null and b/e2e/react-start/optional-params/public/favicon.png differ
diff --git a/e2e/react-start/optional-params/public/script.js b/e2e/react-start/optional-params/public/script.js
new file mode 100644
index 0000000000..897477e7d0
--- /dev/null
+++ b/e2e/react-start/optional-params/public/script.js
@@ -0,0 +1,2 @@
+console.log('SCRIPT_1 loaded')
+window.SCRIPT_1 = true
diff --git a/e2e/react-start/optional-params/public/script2.js b/e2e/react-start/optional-params/public/script2.js
new file mode 100644
index 0000000000..819af30daf
--- /dev/null
+++ b/e2e/react-start/optional-params/public/script2.js
@@ -0,0 +1,2 @@
+console.log('SCRIPT_2 loaded')
+window.SCRIPT_2 = true
diff --git a/e2e/react-start/optional-params/public/site.webmanifest b/e2e/react-start/optional-params/public/site.webmanifest
new file mode 100644
index 0000000000..fa99de77db
--- /dev/null
+++ b/e2e/react-start/optional-params/public/site.webmanifest
@@ -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"
+}
diff --git a/e2e/react-start/optional-params/src/client.tsx b/e2e/react-start/optional-params/src/client.tsx
new file mode 100644
index 0000000000..5fcd1c5f19
--- /dev/null
+++ b/e2e/react-start/optional-params/src/client.tsx
@@ -0,0 +1,19 @@
+// DO NOT DELETE THIS FILE!!!
+// This file is a good smoke test to make sure the custom client entry is working
+import { StrictMode, startTransition } from 'react'
+import { hydrateRoot } from 'react-dom/client'
+import { StartClient } from '@tanstack/react-start'
+import { createRouter } from './router'
+
+console.log("[client-entry]: using custom client entry in 'src/client.tsx'")
+
+const router = createRouter()
+
+startTransition(() => {
+ hydrateRoot(
+ document,
+
+
+ ,
+ )
+})
diff --git a/e2e/react-start/optional-params/src/components/CustomMessage.tsx b/e2e/react-start/optional-params/src/components/CustomMessage.tsx
new file mode 100644
index 0000000000..d00e4eac60
--- /dev/null
+++ b/e2e/react-start/optional-params/src/components/CustomMessage.tsx
@@ -0,0 +1,10 @@
+import * as React from 'react'
+
+export function CustomMessage({ message }: { message: string }) {
+ return (
+
+
This is a custom message:
+
{message}
+
+ )
+}
diff --git a/e2e/react-start/optional-params/src/components/DefaultCatchBoundary.tsx b/e2e/react-start/optional-params/src/components/DefaultCatchBoundary.tsx
new file mode 100644
index 0000000000..15f316681c
--- /dev/null
+++ b/e2e/react-start/optional-params/src/components/DefaultCatchBoundary.tsx
@@ -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 (
+
+
+
+
+ {isRoot ? (
+
+ Home
+
+ ) : (
+ {
+ e.preventDefault()
+ window.history.back()
+ }}
+ >
+ Go Back
+
+ )}
+
+
+ )
+}
diff --git a/e2e/react-start/optional-params/src/components/NotFound.tsx b/e2e/react-start/optional-params/src/components/NotFound.tsx
new file mode 100644
index 0000000000..af4e0e7494
--- /dev/null
+++ b/e2e/react-start/optional-params/src/components/NotFound.tsx
@@ -0,0 +1,25 @@
+import { Link } from '@tanstack/react-router'
+
+export function NotFound({ children }: { children?: any }) {
+ return (
+
+
+ {children ||
The page you are looking for does not exist.
}
+
+
+
+
+ Start Over
+
+
+
+ )
+}
diff --git a/e2e/react-start/optional-params/src/components/RedirectOnClick.tsx b/e2e/react-start/optional-params/src/components/RedirectOnClick.tsx
new file mode 100644
index 0000000000..37b434c2e7
--- /dev/null
+++ b/e2e/react-start/optional-params/src/components/RedirectOnClick.tsx
@@ -0,0 +1,26 @@
+import { useServerFn } from '@tanstack/react-start'
+import { throwRedirect } from './throwRedirect'
+
+interface RedirectOnClickProps {
+ target: 'internal' | 'external'
+ reloadDocument?: boolean
+ externalHost?: string
+}
+
+export function RedirectOnClick({
+ target,
+ reloadDocument,
+ externalHost,
+}: RedirectOnClickProps) {
+ const execute = useServerFn(throwRedirect)
+ return (
+
+ )
+}
diff --git a/e2e/react-start/optional-params/src/components/throwRedirect.ts b/e2e/react-start/optional-params/src/components/throwRedirect.ts
new file mode 100644
index 0000000000..7a21427356
--- /dev/null
+++ b/e2e/react-start/optional-params/src/components/throwRedirect.ts
@@ -0,0 +1,23 @@
+import { redirect } from '@tanstack/react-router'
+import { createServerFn } from '@tanstack/react-start'
+
+export const throwRedirect = createServerFn()
+ .validator(
+ (opts: {
+ target: 'internal' | 'external'
+ reloadDocument?: boolean
+ externalHost?: string
+ }) => opts,
+ )
+ .handler((ctx) => {
+ if (ctx.data.target === 'internal') {
+ throw redirect({
+ to: '/blog/{-$category}',
+ reloadDocument: ctx.data.reloadDocument,
+ })
+ }
+ const href = ctx.data.externalHost ?? 'http://example.com'
+ throw redirect({
+ href,
+ })
+ })
diff --git a/e2e/react-start/optional-params/src/routeTree.gen.ts b/e2e/react-start/optional-params/src/routeTree.gen.ts
new file mode 100644
index 0000000000..45453db105
--- /dev/null
+++ b/e2e/react-start/optional-params/src/routeTree.gen.ts
@@ -0,0 +1,205 @@
+/* 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 type { CreateFileRoute, FileRoutesByPath } from '@tanstack/react-router'
+import type {
+ CreateServerFileRoute,
+ ServerFileRoutesByPath,
+} from '@tanstack/react-start/server'
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as IndexRouteImport } from './routes/index'
+import { Route as BlogChar123CategoryChar125RouteImport } from './routes/blog.{-$category}'
+import { Route as UsersIdChar123TabChar125RouteImport } from './routes/users.$id.{-$tab}'
+import { Route as ApiVChar123VersionChar125Char123EndpointChar125RouteImport } from './routes/api.v{-$version}.{-$endpoint}'
+
+const IndexRoute = IndexRouteImport.update({
+ id: '/',
+ path: '/',
+ getParentRoute: () => rootRouteImport,
+} as any)
+const BlogChar123CategoryChar125Route =
+ BlogChar123CategoryChar125RouteImport.update({
+ id: '/blog/{-$category}',
+ path: '/blog/{-$category}',
+ getParentRoute: () => rootRouteImport,
+ } as any)
+const UsersIdChar123TabChar125Route =
+ UsersIdChar123TabChar125RouteImport.update({
+ id: '/users/$id/{-$tab}',
+ path: '/users/$id/{-$tab}',
+ getParentRoute: () => rootRouteImport,
+ } as any)
+const ApiVChar123VersionChar125Char123EndpointChar125Route =
+ ApiVChar123VersionChar125Char123EndpointChar125RouteImport.update({
+ id: '/api/v{-$version}/{-$endpoint}',
+ path: '/api/v{-$version}/{-$endpoint}',
+ getParentRoute: () => rootRouteImport,
+ } as any)
+
+export interface FileRoutesByFullPath {
+ '/': typeof IndexRoute
+ '/blog/{-$category}': typeof BlogChar123CategoryChar125Route
+ '/api/v{-$version}/{-$endpoint}': typeof ApiVChar123VersionChar125Char123EndpointChar125Route
+ '/users/$id/{-$tab}': typeof UsersIdChar123TabChar125Route
+}
+export interface FileRoutesByTo {
+ '/': typeof IndexRoute
+ '/blog/{-$category}': typeof BlogChar123CategoryChar125Route
+ '/api/v{-$version}/{-$endpoint}': typeof ApiVChar123VersionChar125Char123EndpointChar125Route
+ '/users/$id/{-$tab}': typeof UsersIdChar123TabChar125Route
+}
+export interface FileRoutesById {
+ __root__: typeof rootRouteImport
+ '/': typeof IndexRoute
+ '/blog/{-$category}': typeof BlogChar123CategoryChar125Route
+ '/api/v{-$version}/{-$endpoint}': typeof ApiVChar123VersionChar125Char123EndpointChar125Route
+ '/users/$id/{-$tab}': typeof UsersIdChar123TabChar125Route
+}
+export interface FileRouteTypes {
+ fileRoutesByFullPath: FileRoutesByFullPath
+ fullPaths:
+ | '/'
+ | '/blog/{-$category}'
+ | '/api/v{-$version}/{-$endpoint}'
+ | '/users/$id/{-$tab}'
+ fileRoutesByTo: FileRoutesByTo
+ to:
+ | '/'
+ | '/blog/{-$category}'
+ | '/api/v{-$version}/{-$endpoint}'
+ | '/users/$id/{-$tab}'
+ id:
+ | '__root__'
+ | '/'
+ | '/blog/{-$category}'
+ | '/api/v{-$version}/{-$endpoint}'
+ | '/users/$id/{-$tab}'
+ fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+ IndexRoute: typeof IndexRoute
+ BlogChar123CategoryChar125Route: typeof BlogChar123CategoryChar125Route
+ ApiVChar123VersionChar125Char123EndpointChar125Route: typeof ApiVChar123VersionChar125Char123EndpointChar125Route
+ UsersIdChar123TabChar125Route: typeof UsersIdChar123TabChar125Route
+}
+
+declare module '@tanstack/react-router' {
+ interface FileRoutesByPath {
+ '/': {
+ id: '/'
+ path: '/'
+ fullPath: '/'
+ preLoaderRoute: typeof IndexRouteImport
+ parentRoute: typeof rootRouteImport
+ }
+ '/blog/{-$category}': {
+ id: '/blog/{-$category}'
+ path: '/blog/{-$category}'
+ fullPath: '/blog/{-$category}'
+ preLoaderRoute: typeof BlogChar123CategoryChar125RouteImport
+ parentRoute: typeof rootRouteImport
+ }
+ '/api/v{-$version}/{-$endpoint}': {
+ id: '/api/v{-$version}/{-$endpoint}'
+ path: '/api/v{-$version}/{-$endpoint}'
+ fullPath: '/api/v{-$version}/{-$endpoint}'
+ preLoaderRoute: typeof ApiVChar123VersionChar125Char123EndpointChar125RouteImport
+ parentRoute: typeof rootRouteImport
+ }
+ '/users/$id/{-$tab}': {
+ id: '/users/$id/{-$tab}'
+ path: '/users/$id/{-$tab}'
+ fullPath: '/users/$id/{-$tab}'
+ preLoaderRoute: typeof UsersIdChar123TabChar125RouteImport
+ parentRoute: typeof rootRouteImport
+ }
+ }
+}
+
+declare module './routes/index' {
+ const createFileRoute: CreateFileRoute<
+ '/',
+ FileRoutesByPath['/']['parentRoute'],
+ FileRoutesByPath['/']['id'],
+ FileRoutesByPath['/']['path'],
+ FileRoutesByPath['/']['fullPath']
+ >
+
+ const createServerFileRoute: CreateServerFileRoute<
+ ServerFileRoutesByPath['/']['parentRoute'],
+ ServerFileRoutesByPath['/']['id'],
+ ServerFileRoutesByPath['/']['path'],
+ ServerFileRoutesByPath['/']['fullPath'],
+ unknown
+ >
+}
+declare module './routes/blog.{-$category}' {
+ const createFileRoute: CreateFileRoute<
+ '/blog/{-$category}',
+ FileRoutesByPath['/blog/{-$category}']['parentRoute'],
+ FileRoutesByPath['/blog/{-$category}']['id'],
+ FileRoutesByPath['/blog/{-$category}']['path'],
+ FileRoutesByPath['/blog/{-$category}']['fullPath']
+ >
+
+ const createServerFileRoute: CreateServerFileRoute<
+ ServerFileRoutesByPath['/blog/{-$category}']['parentRoute'],
+ ServerFileRoutesByPath['/blog/{-$category}']['id'],
+ ServerFileRoutesByPath['/blog/{-$category}']['path'],
+ ServerFileRoutesByPath['/blog/{-$category}']['fullPath'],
+ unknown
+ >
+}
+declare module './routes/api.v{-$version}.{-$endpoint}' {
+ const createFileRoute: CreateFileRoute<
+ '/api/v{-$version}/{-$endpoint}',
+ FileRoutesByPath['/api/v{-$version}/{-$endpoint}']['parentRoute'],
+ FileRoutesByPath['/api/v{-$version}/{-$endpoint}']['id'],
+ FileRoutesByPath['/api/v{-$version}/{-$endpoint}']['path'],
+ FileRoutesByPath['/api/v{-$version}/{-$endpoint}']['fullPath']
+ >
+
+ const createServerFileRoute: CreateServerFileRoute<
+ ServerFileRoutesByPath['/api/v{-$version}/{-$endpoint}']['parentRoute'],
+ ServerFileRoutesByPath['/api/v{-$version}/{-$endpoint}']['id'],
+ ServerFileRoutesByPath['/api/v{-$version}/{-$endpoint}']['path'],
+ ServerFileRoutesByPath['/api/v{-$version}/{-$endpoint}']['fullPath'],
+ unknown
+ >
+}
+declare module './routes/users.$id.{-$tab}' {
+ const createFileRoute: CreateFileRoute<
+ '/users/$id/{-$tab}',
+ FileRoutesByPath['/users/$id/{-$tab}']['parentRoute'],
+ FileRoutesByPath['/users/$id/{-$tab}']['id'],
+ FileRoutesByPath['/users/$id/{-$tab}']['path'],
+ FileRoutesByPath['/users/$id/{-$tab}']['fullPath']
+ >
+
+ const createServerFileRoute: CreateServerFileRoute<
+ ServerFileRoutesByPath['/users/$id/{-$tab}']['parentRoute'],
+ ServerFileRoutesByPath['/users/$id/{-$tab}']['id'],
+ ServerFileRoutesByPath['/users/$id/{-$tab}']['path'],
+ ServerFileRoutesByPath['/users/$id/{-$tab}']['fullPath'],
+ unknown
+ >
+}
+
+const rootRouteChildren: RootRouteChildren = {
+ IndexRoute: IndexRoute,
+ BlogChar123CategoryChar125Route: BlogChar123CategoryChar125Route,
+ ApiVChar123VersionChar125Char123EndpointChar125Route:
+ ApiVChar123VersionChar125Char123EndpointChar125Route,
+ UsersIdChar123TabChar125Route: UsersIdChar123TabChar125Route,
+}
+export const routeTree = rootRouteImport
+ ._addFileChildren(rootRouteChildren)
+ ._addFileTypes()
diff --git a/e2e/react-start/optional-params/src/router.tsx b/e2e/react-start/optional-params/src/router.tsx
new file mode 100644
index 0000000000..c76eb0210c
--- /dev/null
+++ b/e2e/react-start/optional-params/src/router.tsx
@@ -0,0 +1,22 @@
+import { createRouter as createTanStackRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+import { DefaultCatchBoundary } from './components/DefaultCatchBoundary'
+import { NotFound } from './components/NotFound'
+
+export function createRouter() {
+ const router = createTanStackRouter({
+ routeTree,
+ defaultPreload: 'intent',
+ defaultErrorComponent: DefaultCatchBoundary,
+ defaultNotFoundComponent: () => ,
+ scrollRestoration: true,
+ })
+
+ return router
+}
+
+declare module '@tanstack/react-router' {
+ interface Register {
+ router: ReturnType
+ }
+}
diff --git a/e2e/react-start/optional-params/src/routes/__root.tsx b/e2e/react-start/optional-params/src/routes/__root.tsx
new file mode 100644
index 0000000000..71a6331975
--- /dev/null
+++ b/e2e/react-start/optional-params/src/routes/__root.tsx
@@ -0,0 +1,124 @@
+///
+import * as React from 'react'
+import {
+ HeadContent,
+ Link,
+ Outlet,
+ Scripts,
+ createRootRoute,
+} from '@tanstack/react-router'
+
+import { DefaultCatchBoundary } from '~/components/DefaultCatchBoundary'
+import { NotFound } from '~/components/NotFound'
+import appCss from '~/styles/app.css?url'
+import { seo } from '~/utils/seo'
+
+export const Route = createRootRoute({
+ head: () => ({
+ meta: [
+ {
+ charSet: 'utf-8',
+ },
+ {
+ name: 'viewport',
+ content: 'width=device-width, initial-scale=1',
+ },
+ ...seo({
+ title: 'Optional Parameters Demo | TanStack Start + Router',
+ description: 'Testing optional parameters in TanStack Start and Router',
+ }),
+ ],
+ links: [
+ { rel: 'stylesheet', href: appCss },
+ {
+ rel: 'apple-touch-icon',
+ sizes: '180x180',
+ href: '/apple-touch-icon.png',
+ },
+ {
+ rel: 'icon',
+ type: 'image/png',
+ sizes: '32x32',
+ href: '/favicon-32x32.png',
+ },
+ {
+ rel: 'icon',
+ type: 'image/png',
+ sizes: '16x16',
+ href: '/favicon-16x16.png',
+ },
+ { rel: 'manifest', href: '/site.webmanifest', color: '#fffff' },
+ { rel: 'icon', href: '/favicon.ico' },
+ ],
+ }),
+ errorComponent: (props) => {
+ return
+ },
+ notFoundComponent: () => ,
+ component: RootComponent,
+})
+
+function RootComponent() {
+ return (
+
+
+
+ )
+}
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+ return (
+
+
+
+
+
+
+
+
+
+ )
+}
diff --git a/e2e/react-start/optional-params/src/routes/api.v{-$version}.{-$endpoint}.tsx b/e2e/react-start/optional-params/src/routes/api.v{-$version}.{-$endpoint}.tsx
new file mode 100644
index 0000000000..9ae5a339fd
--- /dev/null
+++ b/e2e/react-start/optional-params/src/routes/api.v{-$version}.{-$endpoint}.tsx
@@ -0,0 +1,124 @@
+import { Link } from '@tanstack/react-router'
+
+// Mock API data
+const endpoints = {
+ '1': ['overview', 'users', 'posts'],
+ '2': ['overview', 'users', 'posts', 'auth'],
+ '3': ['overview', 'users', 'posts', 'auth', 'webhooks'],
+}
+
+export const Route = createFileRoute({
+ component: APIComponent,
+})
+
+function APIComponent() {
+ const { version = '1', endpoint = 'overview' } = Route.useParams()
+ const availableEndpoints =
+ endpoints[version as keyof typeof endpoints] || endpoints['1']
+
+ return (
+
+
+
+ API Documentation v{version} - {endpoint}
+
+
+
+
+
API Versions
+
+
+ v1
+
+
+ v2
+
+
+ v3
+
+
+
+
+
+
Endpoints
+
+ {availableEndpoints.map((ep) => (
+
+ {ep}
+
+ ))}
+
+
+
+
+
+
+ API v{version} - {endpoint}
+
+
+ Documentation for the{' '}
+ {endpoint}{' '}
+ endpoint in API version {version}.
+
+
+
+
Endpoint Details
+
+ Base URL:{' '}
+ https://api.example.com/v{version}/{endpoint}
+
+
+ Methods: GET, POST
+
+
+ Available in:{' '}
+ {availableEndpoints.join(', ')}
+
+
+
+
+
+
+
Current URL State
+
+ Version (optional):{' '}
+ {version || 'undefined (defaults to 1)'}
+
+
+ Endpoint (optional):{' '}
+ {endpoint || 'undefined (defaults to overview)'}
+
+
+ URL pattern:{' '}
+ /api/v{'{-$version}/{-$endpoint}'}
+
+
+ Note: This uses prefix pattern
+ where 'v' is always present
+
+
+
+ )
+}
diff --git a/e2e/react-start/optional-params/src/routes/blog.{-$category}.tsx b/e2e/react-start/optional-params/src/routes/blog.{-$category}.tsx
new file mode 100644
index 0000000000..f64146229a
--- /dev/null
+++ b/e2e/react-start/optional-params/src/routes/blog.{-$category}.tsx
@@ -0,0 +1,136 @@
+import { Link } from '@tanstack/react-router'
+
+// Mock blog data
+const blogPosts = {
+ tech: [
+ {
+ id: '1',
+ title: 'React Best Practices',
+ slug: 'react-best-practices',
+ category: 'tech',
+ },
+ {
+ id: '2',
+ title: 'TypeScript Tips',
+ slug: 'typescript-tips',
+ category: 'tech',
+ },
+ ],
+ design: [
+ {
+ id: '3',
+ title: 'UI/UX Principles',
+ slug: 'ui-ux-principles',
+ category: 'design',
+ },
+ ],
+ all: [
+ {
+ id: '1',
+ title: 'React Best Practices',
+ slug: 'react-best-practices',
+ category: 'tech',
+ },
+ {
+ id: '2',
+ title: 'TypeScript Tips',
+ slug: 'typescript-tips',
+ category: 'tech',
+ },
+ {
+ id: '3',
+ title: 'UI/UX Principles',
+ slug: 'ui-ux-principles',
+ category: 'design',
+ },
+ {
+ id: '4',
+ title: 'Getting Started',
+ slug: 'getting-started',
+ category: 'general',
+ },
+ ],
+}
+
+export const Route = createFileRoute({
+ component: BlogComponent,
+})
+
+function BlogComponent() {
+ const { category } = Route.useParams()
+
+ const posts =
+ category && category !== 'all'
+ ? blogPosts[category as keyof typeof blogPosts] || []
+ : blogPosts.all
+
+ return (
+
+
+
+ Blog {category ? `- ${category}` : '(All Categories)'}
+
+
+
+
+ All Posts
+
+
+ Tech
+
+
+ Design
+
+
+
+
+ {posts.map((post) => (
+
+
{post.title}
+
+ Category: {post.category}
+
+
+ Slug: {post.slug}
+
+
+ ))}
+ {posts.length === 0 && (
+
+ No posts found in this category.
+
+ )}
+
+
+
+
+
Current URL State
+
+ Category parameter:{' '}
+ {category || 'undefined (no category)'}
+
+
+ URL pattern:{' '}
+ /blog/{'{-$category}'}
+
+
+
+ )
+}
diff --git a/e2e/react-start/optional-params/src/routes/index.tsx b/e2e/react-start/optional-params/src/routes/index.tsx
new file mode 100644
index 0000000000..7912d2bfa4
--- /dev/null
+++ b/e2e/react-start/optional-params/src/routes/index.tsx
@@ -0,0 +1,101 @@
+export const Route = createFileRoute({
+ component: Home,
+})
+
+function Home() {
+ return (
+
+
+
+ Welcome to Optional Parameters Demo
+
+
+ This demo showcases various optional parameter patterns in TanStack
+ Start + Router:
+
+
+
+
+
Blog with Category Filter
+
+ /blog/{'{-$category}'}
+
+
+ Browse blog posts with optional category filtering
+
+
+
+
+
Documentation Versioning
+
+ /docs/{'{-$version}/{-$page}'}
+
+
+ Navigate docs with optional version and page parameters
+
+
+
+
+
User Profiles with Tabs
+
+ /users/$id/{'{-$tab}'}
+
+
+ User profiles with optional tab navigation
+
+
+
+
+
Product Catalog Filters
+
+ /products/{'{-$category}/{-$brand}'}
+
+
+ E-commerce filtering with multiple optional parameters
+
+
+
+
+
File Browser with Extensions
+
+ /files/view{'{-$filename}.{-$ext}'}
+
+
+ File viewing with prefix/suffix optional parameters
+
+
+
+
+
API Documentation
+
+ /api/v{'{-$version}/{-$endpoint}'}
+
+
+ API docs with optional version and endpoint parameters
+
+
+
+
+
+
+
Key Features Tested
+
+ - Single optional parameters (/blog/{'{-$category}'})
+ -
+ Mixed required and optional parameters (/users/$id/{'{-$tab}'})
+
+ -
+ Optional parameters with prefix patterns (/api/v
+ {'{-$version}/{-$endpoint}'})
+
+ - Parameter inheritance between routes
+ - TypeScript type safety in Start + Router
+ - Server-side rendering (SSR) compatibility
+ - File-based routing with optional parameters
+ - Link generation and navigation
+ - Direct URL access
+
+
+
+ )
+}
diff --git a/e2e/react-start/optional-params/src/routes/users.$id.{-$tab}.tsx b/e2e/react-start/optional-params/src/routes/users.$id.{-$tab}.tsx
new file mode 100644
index 0000000000..10a816ced7
--- /dev/null
+++ b/e2e/react-start/optional-params/src/routes/users.$id.{-$tab}.tsx
@@ -0,0 +1,142 @@
+import { Link } from '@tanstack/react-router'
+
+// Mock user data
+const users = {
+ '1': { id: '1', name: 'John Doe', email: 'john@example.com' },
+ '2': { id: '2', name: 'Jane Smith', email: 'jane@example.com' },
+}
+
+export const Route = createFileRoute({
+ component: UserComponent,
+})
+
+function UserComponent() {
+ const { id, tab = 'profile' } = Route.useParams()
+ const user = users[id as keyof typeof users]
+
+ if (!user) {
+ return (
+
+
User Not Found
+
No user found with ID: {id}
+
+ View User 1
+
+
+ )
+ }
+
+ return (
+
+
+
+ {user.name} - {tab}
+
+
+
+
+ Profile
+
+
+ Settings
+
+
+ Activity
+
+
+
+
+ {tab === 'profile' && (
+
+
Profile Information
+
+
+ Name: {user.name}
+
+
+ Email: {user.email}
+
+
+ User ID: {user.id}
+
+
+
+ )}
+ {tab === 'settings' && (
+
+
Settings
+
+ User settings configuration would be displayed here.
+
+
+
+
+
+
+ )}
+ {tab === 'activity' && (
+
+
Recent Activity
+
+ User activity feed would be displayed here.
+
+
+
+
Logged in from Chrome on Windows
+
2 hours ago
+
+
+
Updated profile information
+
1 day ago
+
+
+
+ )}
+
+
+
+
+
Current URL State
+
+ User ID (required): {id}
+
+
+ Tab (optional):{' '}
+ {tab || 'undefined (defaults to profile)'}
+
+
+ URL pattern:{' '}
+ /users/$id/{'{-$tab}'}
+
+
+
+ )
+}
diff --git a/e2e/react-start/optional-params/src/server.ts b/e2e/react-start/optional-params/src/server.ts
new file mode 100644
index 0000000000..77cb4a1316
--- /dev/null
+++ b/e2e/react-start/optional-params/src/server.ts
@@ -0,0 +1,13 @@
+// DO NOT DELETE THIS FILE!!!
+// This file is a good smoke test to make sure the custom server entry is working
+import {
+ createStartHandler,
+ defaultStreamHandler,
+} from '@tanstack/react-start/server'
+import { createRouter } from './router'
+
+console.log("[server-entry]: using custom server entry in 'src/server.ts'")
+
+export default createStartHandler({
+ createRouter,
+})(defaultStreamHandler)
diff --git a/e2e/react-start/optional-params/src/styles/app.css b/e2e/react-start/optional-params/src/styles/app.css
new file mode 100644
index 0000000000..c53c870665
--- /dev/null
+++ b/e2e/react-start/optional-params/src/styles/app.css
@@ -0,0 +1,22 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+ html {
+ color-scheme: light dark;
+ }
+
+ * {
+ @apply border-gray-200 dark:border-gray-800;
+ }
+
+ html,
+ body {
+ @apply text-gray-900 bg-gray-50 dark:bg-gray-950 dark:text-gray-200;
+ }
+
+ .using-mouse * {
+ outline: none !important;
+ }
+}
diff --git a/e2e/react-start/optional-params/src/utils/posts.tsx b/e2e/react-start/optional-params/src/utils/posts.tsx
new file mode 100644
index 0000000000..9fdff27673
--- /dev/null
+++ b/e2e/react-start/optional-params/src/utils/posts.tsx
@@ -0,0 +1,36 @@
+import { notFound } from '@tanstack/react-router'
+import { createServerFn } from '@tanstack/react-start'
+import axios from 'redaxios'
+
+export type PostType = {
+ id: string
+ title: string
+ body: string
+}
+
+export const fetchPost = createServerFn({ method: 'GET' })
+ .validator((postId: string) => postId)
+ .handler(async ({ data: postId }) => {
+ console.info(`Fetching post with id ${postId}...`)
+ const post = await axios
+ .get(`https://jsonplaceholder.typicode.com/posts/${postId}`)
+ .then((r) => r.data)
+ .catch((err) => {
+ console.error(err)
+ if (err.status === 404) {
+ throw notFound()
+ }
+ throw err
+ })
+
+ return post
+ })
+
+export const fetchPosts = createServerFn({ method: 'GET' }).handler(
+ async () => {
+ console.info('Fetching posts...')
+ return axios
+ .get>('https://jsonplaceholder.typicode.com/posts')
+ .then((r) => r.data.slice(0, 10))
+ },
+)
diff --git a/e2e/react-start/optional-params/src/utils/seo.ts b/e2e/react-start/optional-params/src/utils/seo.ts
new file mode 100644
index 0000000000..d18ad84b74
--- /dev/null
+++ b/e2e/react-start/optional-params/src/utils/seo.ts
@@ -0,0 +1,33 @@
+export const seo = ({
+ title,
+ description,
+ keywords,
+ image,
+}: {
+ title: string
+ description?: string
+ image?: string
+ keywords?: string
+}) => {
+ const tags = [
+ { title },
+ { name: 'description', content: description },
+ { name: 'keywords', content: keywords },
+ { name: 'twitter:title', content: title },
+ { name: 'twitter:description', content: description },
+ { name: 'twitter:creator', content: '@tannerlinsley' },
+ { name: 'twitter:site', content: '@tannerlinsley' },
+ { name: 'og:type', content: 'website' },
+ { name: 'og:title', content: title },
+ { name: 'og:description', content: description },
+ ...(image
+ ? [
+ { name: 'twitter:image', content: image },
+ { name: 'twitter:card', content: 'summary_large_image' },
+ { name: 'og:image', content: image },
+ ]
+ : []),
+ ]
+
+ return tags
+}
diff --git a/e2e/react-start/optional-params/src/utils/users.tsx b/e2e/react-start/optional-params/src/utils/users.tsx
new file mode 100644
index 0000000000..46be4b1580
--- /dev/null
+++ b/e2e/react-start/optional-params/src/utils/users.tsx
@@ -0,0 +1,9 @@
+export type User = {
+ id: number
+ name: string
+ email: string
+}
+
+const PORT = process.env.VITE_SERVER_PORT || 3000
+
+export const DEPLOY_URL = `http://localhost:${PORT}`
diff --git a/e2e/react-start/optional-params/tailwind.config.mjs b/e2e/react-start/optional-params/tailwind.config.mjs
new file mode 100644
index 0000000000..e49f4eb776
--- /dev/null
+++ b/e2e/react-start/optional-params/tailwind.config.mjs
@@ -0,0 +1,4 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+ content: ['./src/**/*.{js,jsx,ts,tsx}'],
+}
diff --git a/e2e/react-start/optional-params/tests/optional-params.spec.ts b/e2e/react-start/optional-params/tests/optional-params.spec.ts
new file mode 100644
index 0000000000..5a4e6a8308
--- /dev/null
+++ b/e2e/react-start/optional-params/tests/optional-params.spec.ts
@@ -0,0 +1,436 @@
+import { expect, test } from '@playwright/test'
+
+test.beforeEach(async ({ page }) => {
+ await page.goto('/')
+})
+
+test.describe('Optional Parameters in TanStack Start + Router', () => {
+ test('should display home page with optional parameter examples', async ({
+ page,
+ }) => {
+ await expect(
+ page.getByRole('heading', {
+ name: 'Welcome to Optional Parameters Demo',
+ }),
+ ).toBeVisible()
+ await expect(page.getByText('/blog/{-$category}')).toBeVisible()
+ await expect(page.getByText('/docs/{-$version}/{-$page}')).toBeVisible()
+ await expect(page.getByText('/users/$id/{-$tab}')).toBeVisible()
+ await expect(
+ page.getByText('/products/{-$category}/{-$brand}'),
+ ).toBeVisible()
+ await expect(
+ page.getByText('/files/view{-$filename}.{-$ext}'),
+ ).toBeVisible()
+ await expect(page.getByText('/api/v{-$version}/{-$endpoint}')).toBeVisible()
+ })
+
+ test.describe('Blog Routes - Single Optional Parameter', () => {
+ test('should navigate to blog without category (shows all posts)', async ({
+ page,
+ }) => {
+ await page.getByRole('link', { name: 'Blog' }).click()
+
+ // Check URL matches Start + Router behavior
+ await expect(page).toHaveURL('/blog')
+
+ // Check SSR content is properly rendered
+ await expect(page.getByRole('heading')).toContainText(
+ 'Blog (All Categories)',
+ )
+ await expect(page.getByText('React Best Practices')).toBeVisible()
+ await expect(page.getByText('TypeScript Tips')).toBeVisible()
+ await expect(page.getByText('UI/UX Principles')).toBeVisible()
+ await expect(page.getByText('Getting Started')).toBeVisible()
+
+ // Check URL state display
+ await expect(page.getByText('undefined (no category)')).toBeVisible()
+ })
+
+ test('should navigate to blog with tech category', async ({ page }) => {
+ await page.getByRole('link', { name: 'Blog' }).click()
+ await page.getByTestId('blog-tech-link').click()
+
+ // Check URL
+ await expect(page).toHaveURL('/blog/tech')
+
+ // Check content filtering works
+ await expect(page.getByRole('heading')).toContainText('Blog - tech')
+ await expect(page.getByText('React Best Practices')).toBeVisible()
+ await expect(page.getByText('TypeScript Tips')).toBeVisible()
+ await expect(page.getByText('UI/UX Principles')).not.toBeVisible()
+
+ // Check URL state display
+ await expect(page.getByText('Category parameter: tech')).toBeVisible()
+ })
+
+ test('should navigate to blog with design category', async ({ page }) => {
+ await page.getByRole('link', { name: 'Blog' }).click()
+ await page.getByTestId('blog-design-link').click()
+
+ await expect(page).toHaveURL('/blog/design')
+ await expect(page.getByRole('heading')).toContainText('Blog - design')
+ await expect(page.getByText('UI/UX Principles')).toBeVisible()
+ await expect(page.getByText('React Best Practices')).not.toBeVisible()
+ })
+
+ test('should handle direct URL navigation to blog categories', async ({
+ page,
+ }) => {
+ // Test direct navigation to specific category
+ await page.goto('/blog/tech')
+ await expect(page.getByRole('heading')).toContainText('Blog - tech')
+ await expect(page.getByText('React Best Practices')).toBeVisible()
+
+ // Test navigation back to all categories
+ await page.getByTestId('blog-all-link').click()
+ await expect(page).toHaveURL('/blog')
+ await expect(page.getByText('Getting Started')).toBeVisible()
+ })
+ })
+
+ test.describe('User Routes - Mixed Required/Optional Parameters', () => {
+ test('should navigate to user without tab (defaults to profile)', async ({
+ page,
+ }) => {
+ await page.getByRole('link', { name: 'Users' }).click()
+
+ await expect(page).toHaveURL('/users/1')
+ await expect(page.getByRole('heading')).toContainText(
+ 'John Doe - profile',
+ )
+ await expect(page.getByText('Name: John Doe')).toBeVisible()
+ await expect(page.getByText('Email: john@example.com')).toBeVisible()
+
+ // Check URL state display
+ await expect(page.getByText('User ID (required): 1')).toBeVisible()
+ await expect(page.getByText('Tab (optional): profile')).toBeVisible()
+ })
+
+ test('should navigate to user settings tab', async ({ page }) => {
+ await page.getByRole('link', { name: 'Users' }).click()
+ await page.getByTestId('user-settings-link').click()
+
+ await expect(page).toHaveURL('/users/1/settings')
+ await expect(page.getByRole('heading')).toContainText(
+ 'John Doe - settings',
+ )
+ await expect(
+ page.getByText('User settings configuration would be displayed here'),
+ ).toBeVisible()
+ await expect(page.getByText('Email notifications')).toBeVisible()
+ })
+
+ test('should navigate to user activity tab', async ({ page }) => {
+ await page.getByRole('link', { name: 'Users' }).click()
+ await page.getByTestId('user-activity-link').click()
+
+ await expect(page).toHaveURL('/users/1/activity')
+ await expect(page.getByRole('heading')).toContainText(
+ 'John Doe - activity',
+ )
+ await expect(
+ page.getByText('User activity feed would be displayed here'),
+ ).toBeVisible()
+ await expect(
+ page.getByText('Logged in from Chrome on Windows'),
+ ).toBeVisible()
+ })
+
+ test('should handle direct URL navigation to user tabs', async ({
+ page,
+ }) => {
+ // Direct navigation to settings
+ await page.goto('/users/1/settings')
+ await expect(page.getByRole('heading')).toContainText(
+ 'John Doe - settings',
+ )
+
+ // Direct navigation to profile (no tab)
+ await page.goto('/users/1')
+ await expect(page.getByRole('heading')).toContainText(
+ 'John Doe - profile',
+ )
+ })
+
+ test('should handle non-existent user gracefully', async ({ page }) => {
+ await page.goto('/users/999')
+ await expect(page.getByText('User Not Found')).toBeVisible()
+ await expect(page.getByText('No user found with ID: 999')).toBeVisible()
+ })
+
+ test('should maintain correct active state for tabs', async ({ page }) => {
+ await page.getByRole('link', { name: 'Users' }).click()
+
+ // Profile should be active by default (through background color)
+ const profileLink = page.getByTestId('user-profile-link')
+ const settingsLink = page.getByTestId('user-settings-link')
+
+ // Click settings
+ await settingsLink.click()
+ await expect(page).toHaveURL('/users/1/settings')
+
+ // Navigate back to profile
+ await profileLink.click()
+ await expect(page).toHaveURL('/users/1')
+ })
+ })
+
+ test.describe('API Routes - Optional Parameters with Prefix Pattern', () => {
+ test('should show API docs with default version and endpoint', async ({
+ page,
+ }) => {
+ await page.getByRole('link', { name: 'API' }).click()
+
+ // This should work with Start + Router defaults
+ await expect(page).toHaveURL('/api/v1/overview')
+
+ await expect(page.getByRole('heading')).toContainText(
+ 'API Documentation v1 - overview',
+ )
+ await expect(
+ page.getByText('Available in: overview, users, posts'),
+ ).toBeVisible()
+
+ // Check URL state display
+ await expect(page.getByText('Version (optional): 1')).toBeVisible()
+ await expect(
+ page.getByText('Endpoint (optional): overview'),
+ ).toBeVisible()
+ })
+
+ test('should navigate to different API version', async ({ page }) => {
+ await page.getByRole('link', { name: 'API' }).click()
+ await page.getByTestId('api-v2-link').click()
+
+ await expect(page).toHaveURL('/api/v2/overview')
+ await expect(page.getByRole('heading')).toContainText(
+ 'API Documentation v2 - overview',
+ )
+ await expect(
+ page.getByText('Available in: overview, users, posts, auth'),
+ ).toBeVisible()
+ })
+
+ test('should navigate to specific endpoint in version', async ({
+ page,
+ }) => {
+ await page.getByRole('link', { name: 'API' }).click()
+ await page.getByTestId('api-v3-link').click()
+ await page.getByTestId('api-endpoint-webhooks-link').click()
+
+ await expect(page).toHaveURL('/api/v3/webhooks')
+ await expect(page.getByRole('heading')).toContainText(
+ 'API Documentation v3 - webhooks',
+ )
+ await expect(
+ page.getByText(
+ 'Documentation for the webhooks endpoint in API version 3',
+ ),
+ ).toBeVisible()
+ })
+
+ test('should show different endpoints for different versions', async ({
+ page,
+ }) => {
+ await page.getByRole('link', { name: 'API' }).click()
+
+ // v1 should not have webhooks or auth
+ await expect(
+ page.getByTestId('api-endpoint-webhooks-link'),
+ ).not.toBeVisible()
+ await expect(page.getByTestId('api-endpoint-auth-link')).not.toBeVisible()
+
+ // v2 should have auth but not webhooks
+ await page.getByTestId('api-v2-link').click()
+ await expect(page.getByTestId('api-endpoint-auth-link')).toBeVisible()
+ await expect(
+ page.getByTestId('api-endpoint-webhooks-link'),
+ ).not.toBeVisible()
+
+ // v3 should have webhooks
+ await page.getByTestId('api-v3-link').click()
+ await expect(page.getByTestId('api-endpoint-webhooks-link')).toBeVisible()
+ })
+
+ test('should handle direct URL navigation to API endpoints', async ({
+ page,
+ }) => {
+ // Test direct navigation to specific version/endpoint
+ await page.goto('/api/v2/auth')
+ await expect(page.getByRole('heading')).toContainText(
+ 'API Documentation v2 - auth',
+ )
+
+ // Test navigation to base API (should default)
+ await page.goto('/api')
+ await expect(page.getByRole('heading')).toContainText(
+ 'API Documentation v1 - overview',
+ )
+ })
+ })
+
+ test.describe('Server-Side Rendering (SSR) with Optional Parameters', () => {
+ test('should properly server-render pages with optional parameters', async ({
+ page,
+ }) => {
+ // Navigate to a route with optional parameters
+ await page.goto('/blog/tech')
+
+ // The content should be available immediately (SSR)
+ await expect(page.getByRole('heading')).toContainText('Blog - tech')
+ await expect(page.getByText('React Best Practices')).toBeVisible()
+
+ // Check that the page was server-rendered by looking for hydration
+ const blogTitle = page.getByRole('heading')
+ await expect(blogTitle).toBeVisible()
+ })
+
+ test('should handle optional parameters in SSR for API routes', async ({
+ page,
+ }) => {
+ await page.goto('/api/v2/auth')
+
+ // Should immediately show the content (SSR)
+ await expect(page.getByRole('heading')).toContainText(
+ 'API Documentation v2 - auth',
+ )
+ await expect(
+ page.getByText('Documentation for the auth endpoint in API version 2'),
+ ).toBeVisible()
+ })
+
+ test('should handle missing optional parameters in SSR', async ({
+ page,
+ }) => {
+ await page.goto('/users/1')
+
+ // Should immediately show default tab content (SSR)
+ await expect(page.getByRole('heading')).toContainText(
+ 'John Doe - profile',
+ )
+ await expect(page.getByText('Profile Information')).toBeVisible()
+ })
+ })
+
+ test.describe('Navigation and URL Patterns in Start Context', () => {
+ test('should handle browser back/forward with optional parameters', async ({
+ page,
+ }) => {
+ // Navigate through several pages
+ await page.getByRole('link', { name: 'Blog' }).click()
+ await page.getByTestId('blog-tech-link').click()
+ await page.getByRole('link', { name: 'Users' }).click()
+ await page.getByTestId('user-settings-link').click()
+
+ // Go back through history
+ await page.goBack()
+ await expect(page).toHaveURL('/users/1')
+
+ await page.goBack()
+ await expect(page).toHaveURL('/blog/tech')
+
+ await page.goBack()
+ await expect(page).toHaveURL('/blog')
+
+ // Go forward
+ await page.goForward()
+ await expect(page).toHaveURL('/blog/tech')
+ })
+
+ test('should handle complex navigation scenarios', async ({ page }) => {
+ // Start with blog
+ await page.getByRole('link', { name: 'Blog' }).click()
+ await page.getByTestId('blog-tech-link').click()
+ await expect(page).toHaveURL('/blog/tech')
+
+ // Navigate to API
+ await page.getByRole('link', { name: 'API' }).click()
+ await expect(page).toHaveURL('/api/v1/overview')
+
+ // Navigate to users
+ await page.getByRole('link', { name: 'Users' }).click()
+ await page.getByTestId('user-activity-link').click()
+ await expect(page).toHaveURL('/users/1/activity')
+ })
+
+ test('should handle edge cases and invalid routes', async ({ page }) => {
+ // Invalid category
+ await page.goto('/blog/invalid-category')
+ await expect(page.getByRole('heading')).toContainText(
+ 'Blog - invalid-category',
+ )
+ await expect(
+ page.getByText('No posts found in this category'),
+ ).toBeVisible()
+
+ // Invalid user ID
+ await page.goto('/users/invalid')
+ await expect(page.getByText('User Not Found')).toBeVisible()
+ })
+ })
+
+ test.describe('TypeScript Integration and Type Safety', () => {
+ test('should properly type optional parameters in Start context', async ({
+ page,
+ }) => {
+ // This test verifies that the TypeScript compilation works correctly
+ // and that optional parameters are properly typed in the Start context
+
+ await page.getByRole('link', { name: 'Blog' }).click()
+
+ // The fact that the app loads and navigation works indicates
+ // that TypeScript compilation succeeded with proper types
+ await expect(page.getByRole('heading')).toContainText('Blog')
+
+ // Navigate through various optional parameter combinations
+ await page.getByTestId('blog-tech-link').click()
+ await expect(page).toHaveURL('/blog/tech')
+
+ await page.getByRole('link', { name: 'API' }).click()
+ await page.getByTestId('api-v2-link').click()
+ await page.getByTestId('api-endpoint-auth-link').click()
+ await expect(page).toHaveURL('/api/v2/auth')
+ })
+ })
+
+ test.describe('Start-Specific Features with Optional Parameters', () => {
+ test('should handle file-based routing with optional parameters', async ({
+ page,
+ }) => {
+ // Test that file-based routes with optional parameters work correctly
+ await page.goto('/blog/tech')
+ await expect(
+ page.getByText('URL pattern: /blog/{-$category}'),
+ ).toBeVisible()
+
+ await page.goto('/users/1/settings')
+ await expect(
+ page.getByText('URL pattern: /users/$id/{-$tab}'),
+ ).toBeVisible()
+
+ await page.goto('/api/v2/auth')
+ await expect(
+ page.getByText('URL pattern: /api/v{-$version}/{-$endpoint}'),
+ ).toBeVisible()
+ })
+
+ test('should maintain state during navigation in Start app', async ({
+ page,
+ }) => {
+ // Test that Start maintains proper state during navigation
+ await page.getByRole('link', { name: 'Users' }).click()
+ await page.getByTestId('user-settings-link').click()
+
+ // Navigate to another section and back
+ await page.getByRole('link', { name: 'Blog' }).click()
+ await page.getByRole('link', { name: 'Users' }).click()
+
+ // Should remember we were on user 1 but default back to profile tab
+ await expect(page).toHaveURL('/users/1')
+ await expect(page.getByRole('heading')).toContainText(
+ 'John Doe - profile',
+ )
+ })
+ })
+})
diff --git a/e2e/react-start/optional-params/tsconfig.json b/e2e/react-start/optional-params/tsconfig.json
new file mode 100644
index 0000000000..b3a2d67dfa
--- /dev/null
+++ b/e2e/react-start/optional-params/tsconfig.json
@@ -0,0 +1,22 @@
+{
+ "include": ["**/*.ts", "**/*.tsx", "public/script*.js"],
+ "compilerOptions": {
+ "strict": true,
+ "esModuleInterop": true,
+ "jsx": "react-jsx",
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "lib": ["DOM", "DOM.Iterable", "ES2022"],
+ "isolatedModules": true,
+ "resolveJsonModule": true,
+ "skipLibCheck": true,
+ "target": "ES2022",
+ "allowJs": true,
+ "forceConsistentCasingInFileNames": true,
+ "baseUrl": ".",
+ "paths": {
+ "~/*": ["./src/*"]
+ },
+ "noEmit": true
+ }
+}
diff --git a/e2e/react-start/optional-params/vite.config.ts b/e2e/react-start/optional-params/vite.config.ts
new file mode 100644
index 0000000000..2b9454c587
--- /dev/null
+++ b/e2e/react-start/optional-params/vite.config.ts
@@ -0,0 +1,15 @@
+import { defineConfig } from 'vite'
+import tsConfigPaths from 'vite-tsconfig-paths'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+
+export default defineConfig({
+ server: {
+ port: 3002,
+ },
+ plugins: [
+ tsConfigPaths({
+ projects: ['./tsconfig.json'],
+ }),
+ tanstackStart({ tsr: { verboseFileRoutes: false } }),
+ ],
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6973077867..152ab378bf 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1292,6 +1292,73 @@ importers:
specifier: ^5.1.4
version: 5.1.4(typescript@5.8.2)(vite@6.3.5(@types/node@22.13.4)(jiti@2.4.2)(lightningcss@1.29.2)(terser@5.37.0)(tsx@4.20.3)(yaml@2.7.0))
+ e2e/react-start/optional-params:
+ dependencies:
+ '@tanstack/react-router':
+ specifier: workspace:*
+ version: link:../../../packages/react-router
+ '@tanstack/react-router-devtools':
+ specifier: workspace:^
+ version: link:../../../packages/react-router-devtools
+ '@tanstack/react-start':
+ specifier: workspace:*
+ version: link:../../../packages/react-start
+ react:
+ specifier: ^19.0.0
+ version: 19.0.0
+ react-dom:
+ specifier: ^19.0.0
+ version: 19.0.0(react@19.0.0)
+ redaxios:
+ specifier: ^0.5.1
+ version: 0.5.1
+ tailwind-merge:
+ specifier: ^2.6.0
+ version: 2.6.0
+ vite:
+ specifier: 6.3.5
+ version: 6.3.5(@types/node@22.13.4)(jiti@2.4.2)(lightningcss@1.29.2)(terser@5.37.0)(tsx@4.20.3)(yaml@2.7.0)
+ zod:
+ specifier: ^3.24.2
+ version: 3.25.57
+ devDependencies:
+ '@playwright/test':
+ specifier: ^1.52.0
+ version: 1.52.0
+ '@tanstack/router-e2e-utils':
+ specifier: workspace:^
+ version: link:../../e2e-utils
+ '@types/node':
+ specifier: ^22.10.2
+ version: 22.13.4
+ '@types/react':
+ specifier: ^19.0.8
+ version: 19.0.8
+ '@types/react-dom':
+ specifier: ^19.0.3
+ version: 19.0.3(@types/react@19.0.8)
+ '@vitejs/plugin-react':
+ specifier: ^4.3.4
+ version: 4.6.0(vite@6.3.5(@types/node@22.13.4)(jiti@2.4.2)(lightningcss@1.29.2)(terser@5.37.0)(tsx@4.20.3)(yaml@2.7.0))
+ autoprefixer:
+ specifier: ^10.4.20
+ version: 10.4.20(postcss@8.5.3)
+ combinate:
+ specifier: ^1.1.11
+ version: 1.1.11
+ postcss:
+ specifier: ^8.5.1
+ version: 8.5.3
+ tailwindcss:
+ specifier: ^3.4.17
+ version: 3.4.17
+ typescript:
+ specifier: ^5.7.2
+ version: 5.8.3
+ vite-tsconfig-paths:
+ specifier: ^5.1.4
+ version: 5.1.4(typescript@5.8.3)(vite@6.3.5(@types/node@22.13.4)(jiti@2.4.2)(lightningcss@1.29.2)(terser@5.37.0)(tsx@4.20.3)(yaml@2.7.0))
+
e2e/react-start/scroll-restoration:
dependencies:
'@tanstack/react-router':