@tanstack/react-router 1.132.47 → 1.133.3

package/dist/llms/rules/setup-and-architecture.js

@@ -161,247 +161,139 @@ Enough overview, there's so much more to do with TanStack Router. Hit that next
 
 # Quick Start
 
-If you're feeling impatient and prefer to skip all of our wonderful documentation, here is the bare minimum to get going with TanStack Router using both file-based route generation and code-based route configuration:
+TanStack Router can be quickly added to any existing React project or used to scaffold a new one.
 
-## Using File-Based Route Generation
+## TanStack Router Installation
 
-File based route generation (through Vite, and other supported bundlers) is the recommended way to use TanStack Router as it provides the best experience, performance, and ergonomics for the least amount of effort.
+### Requirements
 
-### Scaffolding Your First TanStack Router Project
+Before installing TanStack router, please ensure your project meets the following requirements:
 
-\`\`\`sh
-npx create-tsrouter-app@latest my-app --template file-router
-\`\`\`
+[//]: # 'Requirements'
+
+- \`react\` v18 or later with \`createRoot\` support.
+- \`react-dom\` v18 or later.
 
-See [create-tsrouter-app](https://github.com/TanStack/create-tsrouter-app/tree/main/cli/create-tsrouter-app) for more options.
+[//]: # 'Requirements'
 
-### Manual Setup
+> [!NOTE] Using TypeScript (\`v5.3.x or higher\`) is recommended for the best development experience, though not strictly required. We aim to support the last 5 minor versions of TypeScript, but using the latest version will help avoid potential issues.
 
-Alternatively, you can manually setup the project using the following steps:
+TanStack Router is currently only compatible with React (with ReactDOM) and Solid. If you're interested in contributing to support other frameworks, such as React Native, Angular, or Vue, please reach out to us on [Discord](https://tlinz.com/discord).
 
-#### Install TanStack Router, Vite Plugin, and the Router Devtools
+### Download and Install
+
+To install TanStack Router in your project, run the following command using your preferred package manager:
+
+[//]: # 'installCommand'
 
 \`\`\`sh
-npm install @tanstack/react-router @tanstack/react-router-devtools
-npm install -D @tanstack/router-plugin
-# or
-pnpm add @tanstack/react-router @tanstack/react-router-devtools
-pnpm add -D @tanstack/router-plugin
+npm install @tanstack/router
 # or
-yarn add @tanstack/react-router @tanstack/react-router-devtools
-yarn add -D @tanstack/router-plugin
+pnpm add @tanstack/router
+#or
+yarn add @tanstack/router
 # or
-bun add @tanstack/react-router @tanstack/react-router-devtools
-bun add -D @tanstack/router-plugin
+bun add @tanstack/router
 # or
-deno add npm:@tanstack/react-router npm:@tanstack/router-plugin npm:@tanstack/react-router-devtools
+deno add npm:@tanstack/router
 \`\`\`
 
-#### Configure the Vite Plugin
+[//]: # 'installCommand'
 
-\`\`\`tsx
-// vite.config.ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import { tanstackRouter } from '@tanstack/router-plugin/vite'
+Once installed, you can verify the installation by checking your \`package.json\` file for the \`@tanstack/router\` dependency.
 
-// https://vitejs.dev/config/
-export default defineConfig({
-  plugins: [
-    // Please make sure that '@tanstack/router-plugin' is passed before '@vitejs/plugin-react'
-    tanstackRouter({
-      target: 'react',
-      autoCodeSplitting: true,
-    }),
-    react(),
-    // ...,
-  ],
-})
+[//]: # 'packageJson'
+
+\`\`\`json
+{
+  "dependencies": {
+    "@tanstack/react-router": "^x.x.x"
+  }
+}
 \`\`\`
 
-> [!TIP]
-> If you are not using Vite, or any of the supported bundlers, you can check out the [TanStack Router CLI](../routing/installation-with-router-cli.md) guide for more info.
+[//]: # 'packageJson'
 
-Create the following files:
+## New Project Setup
 
-- \`src/routes/__root.tsx\` (with two '\`_\`' characters)
-- \`src/routes/index.tsx\`
-- \`src/routes/about.tsx\`
-- \`src/main.tsx\`
+To quickly scaffold a new project with TanStack Router, you can use the \`create-tsrouter-app\` command-line tool. This tool sets up a new React application with TanStack Router pre-configured, allowing you to get started quickly.
 
-#### \`src/routes/__root.tsx\`
+> [!TIP] For full details on available options and templates, visit the [\`create-tsrouter-app\` documentation](https://github.com/TanStack/create-tsrouter-app/tree/main/cli/create-tsrouter-app).
 
-\`\`\`tsx
-import { createRootRoute, Link, Outlet } from '@tanstack/react-router'
-import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
+To create a new project, run the following command in your terminal:
 
-const RootLayout = () => (
-  <>
-    <div className="p-2 flex gap-2">
-      <Link to="/" className="[&.active]:font-bold">
-        Home
-      </Link>{' '}
-      <Link to="/about" className="[&.active]:font-bold">
-        About
-      </Link>
-    </div>
-    <hr />
-    <Outlet />
-    <TanStackRouterDevtools />
-  </>
-)
+[//]: # 'createAppCommand'
 
-export const Route = createRootRoute({ component: RootLayout })
+\`\`\`sh
+npx create-tsrouter-app@latest
 \`\`\`
 
-#### \`src/routes/index.tsx\`
-
-\`\`\`tsx
-import { createFileRoute } from '@tanstack/react-router'
+[//]: # 'createAppCommand'
 
-export const Route = createFileRoute('/')({
-  component: Index,
-})
+The CLI will guide you through a short series of prompts to customize your setup, including options for:
 
-function Index() {
-  return (
-    <div className="p-2">
-      <h3>Welcome Home!</h3>
-    </div>
-  )
-}
-\`\`\`
+[//]: # 'CLIPrompts'
 
-#### \`src/routes/about.tsx\`
+- File-based or code-based route configuration
+- TypeScript support
+- Tailwind CSS integration
+- Toolchain setup
+- Git initialization
 
-\`\`\`tsx
-import { createFileRoute } from '@tanstack/react-router'
+[//]: # 'CLIPrompts'
 
-export const Route = createFileRoute('/about')({
-  component: About,
-})
+Once complete, a new React project will be generated with TanStack Router installed and ready to use. All dependencies are automatically installed, so you can jump straight into development:
 
-function About() {
-  return <div className="p-2">Hello from About!</div>
-}
+\`\`\`sh
+cd your-project-name
+npm run dev
 \`\`\`
 
-#### \`src/main.tsx\`
+### Routing Options
 
-Regardless of whether you are using the \`@tanstack/router-plugin\` package and running the \`npm run dev\`/\`npm run build\` scripts, or manually running the \`tsr watch\`/\`tsr generate\` commands from your package scripts, the route tree file will be generated at \`src/routeTree.gen.ts\`.
+TanStack Router supports both file-based and code-based route configurations, allowing you to choose the approach that best fits your workflow.
 
-Import the generated route tree and create a new router instance:
+#### File-Based Route Generation
 
-\`\`\`tsx
-import { StrictMode } from 'react'
-import ReactDOM from 'react-dom/client'
-import { RouterProvider, createRouter } from '@tanstack/react-router'
+The file-based approach is the recommended option for most projects. It automatically creates routes based on your file structure, giving you the best mix of performance, simplicity, and developer experience.
 
-// Import the generated route tree
-import { routeTree } from './routeTree.gen'
+To create a new project using file-based route generation, run the following command:
 
-// Create a new router instance
-const router = createRouter({ routeTree })
-
-// Register the router instance for type safety
-declare module '@tanstack/react-router' {
-  interface Register {
-    router: typeof router
-  }
-}
+[//]: # 'createAppCommandFileBased'
 
-// Render the app
-const rootElement = document.getElementById('root')!
-if (!rootElement.innerHTML) {
-  const root = ReactDOM.createRoot(rootElement)
-  root.render(
-    <StrictMode>
-      <RouterProvider router={router} />
-    </StrictMode>,
-  )
-}
+\`\`\`sh
+npx create-tsrouter-app@latest my-app --template file-router
 \`\`\`
 
-If you are working with this pattern you should change the \`id\` of the root \`<div>\` on your \`index.html\` file to \`<div id='root'></div>\`
+[//]: # 'createAppCommandFileBased'
 
-## Using Code-Based Route Configuration
+This command sets up a new directory called \`my-app\` with everything configured. Once setup completes, you can then start your development server and begin building your application:
 
-> [!IMPORTANT]
-> The following example shows how to configure routes using code, and for simplicity's sake is in a single file for this demo. While code-based generation allows you to declare many routes and even the router instance in a single file, we recommend splitting your routes into separate files for better organization and performance as your application grows.
+\`\`\`sh
+cd my-app
+npm run dev
+\`\`\`
 
-\`\`\`tsx
-import { StrictMode } from 'react'
-import ReactDOM from 'react-dom/client'
-import {
-  Outlet,
-  RouterProvider,
-  Link,
-  createRouter,
-  createRoute,
-  createRootRoute,
-} from '@tanstack/react-router'
-import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
+#### Code-Based Route Configuration
 
-const rootRoute = createRootRoute({
-  component: () => (
-    <>
-      <div className="p-2 flex gap-2">
-        <Link to="/" className="[&.active]:font-bold">
-          Home
-        </Link>{' '}
-        <Link to="/about" className="[&.active]:font-bold">
-          About
-        </Link>
-      </div>
-      <hr />
-      <Outlet />
-      <TanStackRouterDevtools />
-    </>
-  ),
-})
+If you prefer to define routes programmatically, you can use the code-based route configuration. This approach gives you full control over routing logic while maintaining the same project scaffolding workflow.
 
-const indexRoute = createRoute({
-  getParentRoute: () => rootRoute,
-  path: '/',
-  component: function Index() {
-    return (
-      <div className="p-2">
-        <h3>Welcome Home!</h3>
-      </div>
-    )
-  },
-})
+[//]: # 'createAppCommandCodeBased'
 
-const aboutRoute = createRoute({
-  getParentRoute: () => rootRoute,
-  path: '/about',
-  component: function About() {
-    return <div className="p-2">Hello from About!</div>
-  },
-})
+\`\`\`sh
+npx create-tsrouter-app@latest my-app
+\`\`\`
 
-const routeTree = rootRoute.addChildren([indexRoute, aboutRoute])
+[//]: # 'createAppCommandCodeBased'
 
-const router = createRouter({ routeTree })
+Similar to the file-based setup, this command creates a new directory called \`my-app\` with TanStack Router configured for code-based routing. After setup, navigate to your project directory and start the development server:
 
-declare module '@tanstack/react-router' {
-  interface Register {
-    router: typeof router
-  }
-}
-
-const rootElement = document.getElementById('app')!
-if (!rootElement.innerHTML) {
-  const root = ReactDOM.createRoot(rootElement)
-  root.render(
-    <StrictMode>
-      <RouterProvider router={router} />
-    </StrictMode>,
-  )
-}
+\`\`\`sh
+cd my-app
+npm run dev
 \`\`\`
 
-If you glossed over these examples or didn't understand something, we don't blame you, because there's so much more to learn to really take advantage of TanStack Router! Let's move on.
+With either approach, you can now start building your React application with TanStack Router!
 
 # Devtools
 
@@ -593,37 +485,748 @@ function App() {
   - Specifies a Shadow DOM target for the devtools.
   - By default, devtool styles are applied to the \`<head>\` tag of the main document (light DOM). When a \`shadowDOMTarget\` is provided, styles will be applied within this Shadow DOM instead.
 
-# Migration from React Router Checklist
-
-**_If your UI is blank, open the console, and you will probably have some errors that read something along the lines of \`cannot use 'useNavigate' outside of context\` . This means there are React Router api’s that are still imported and referenced that you need to find and remove. The easiest way to make sure you find all React Router imports is to uninstall \`react-router-dom\` and then you should get typescript errors in your files. Then you will know what to change to a \`@tanstack/react-router\` import._**
-
-Here is the [example repo](https://github.com/Benanna2019/SickFitsForEveryone/tree/migrate-to-tanstack/router/React-Router)
-
-- [ ] Install Router - \`npm i @tanstack/react-router\` (see [detailed installation guide](../how-to/install.md))
-- [ ] **Optional:** Uninstall React Router to get TypeScript errors on imports.
-  - At this point I don’t know if you can do a gradual migration, but it seems likely you could have multiple router providers, not desirable.
-  - The api’s between React Router and TanStack Router are very similar and could most likely be handled in a sprint cycle or two if that is your companies way of doing things.
-- [ ] Create Routes for each existing React Router route we have
-- [ ] Create root route
-- [ ] Create router instance
-- [ ] Add global module in main.tsx
-- [ ] Remove any React Router (\`createBrowserRouter\` or \`BrowserRouter\`), \`Routes\`, and \`Route\` Components from main.tsx
-- [ ] **Optional:** Refactor \`render\` function for custom setup/providers - The repo referenced above has an example - This was necessary in the case of Supertokens. Supertoken has a specific setup with React Router and a different setup with all other React implementations
-- [ ] Set RouterProvider and pass it the router as the prop
-- [ ] Replace all instances of React Router \`Link\` component with \`@tanstack/react-router\` \`Link\` component
-  - [ ] Add \`to\` prop with literal path
-  - [ ] Add \`params\` prop, where necessary with params like so \`params={{ orderId: order.id }}\`
-- [ ] Replace all instances of React Router \`useNavigate\` hook with \`@tanstack/react-router\` \`useNavigate\` hook
-  - [ ] Set \`to\` property and \`params\` property where needed
-- [ ] Replace any React Router \`Outlet\`'s with the \`@tanstack/react-router\` equivalent
-- [ ] If you are using \`useSearchParams\` hook from React Router, move the search params default value to the validateSearch property on a Route definition.
-  - [ ] Instead of using the \`useSearchParams\` hook, use \`@tanstack/react-router\` \`Link\`'s search property to update the search params state
-  - [ ] To read search params you can do something like the following
-    - \`const { page } = useSearch({ from: productPage.fullPath })\`
-- [ ] If using React Router’s \`useParams\` hook, update the import to be from \`@tanstack/react-router\` and set the \`from\` property to the literal path name where you want to read the params object from
-  - So say we have a route with the path name \`orders/$orderid\`.
-  - In the \`useParams\` hook we would set up our hook like so: \`const params = useParams({ from: "/orders/$orderId" })\`
-  - Then wherever we wanted to access the order id we would get it off of the params object \`params.orderId\`
+# How to Migrate from React Router v7
+
+This guide provides a step-by-step process to migrate your application from React Router v7 to TanStack Router. We'll cover the complete migration process from removing React Router dependencies to implementing TanStack Router's type-safe routing patterns.
+
+## Quick Start
+
+**Time Required:** 2-4 hours depending on app complexity  
+**Difficulty:** Intermediate  
+**Prerequisites:** Basic React knowledge, existing React Router v7 app
+
+### What You'll Accomplish
+
+- Remove React Router v7 dependencies and components
+- Install and configure TanStack Router
+- Convert route definitions to file-based routing
+- Update navigation components and hooks
+- Implement type-safe routing patterns
+- Handle search params and dynamic routes
+- Migrate from React Router v7's new features to TanStack Router equivalents
+
+---
+
+## Complete Migration Process
+
+### Step 1: Prepare for Migration
+
+Before making any changes, prepare your environment and codebase:
+
+**1.1 Create a backup branch**
+
+\`\`\`bash
+git checkout -b migrate-to-tanstack-router
+git push -u origin migrate-to-tanstack-router
+\`\`\`
+
+**1.2 Install TanStack Router (keep React Router temporarily)**
+
+\`\`\`bash
+# Install TanStack Router
+npm install @tanstack/react-router
+
+# Install development dependencies
+npm install -D @tanstack/router-plugin @tanstack/react-router-devtools
+\`\`\`
+
+**1.3 Set up the router plugin for your bundler**
+
+For **Vite** users, update your \`vite.config.ts\`:
+
+\`\`\`typescript
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { tanstackRouter } from '@tanstack/router-plugin/vite'
+
+export default defineConfig({
+  plugins: [
+    tanstackRouter(), // Add this before react plugin
+    react(),
+  ],
+})
+\`\`\`
+
+For **other bundlers**, see our [bundler configuration guides](../routing/).
+
+### Step 2: Create TanStack Router Configuration
+
+**2.1 Create router configuration file**
+
+Create \`tsr.config.json\` in your project root:
+
+\`\`\`json
+{
+  "routesDirectory": "./src/routes",
+  "generatedRouteTree": "./src/routeTree.gen.ts",
+  "quoteStyle": "single"
+}
+\`\`\`
+
+**2.2 Create routes directory**
+
+\`\`\`bash
+mkdir src/routes
+\`\`\`
+
+### Step 3: Convert Your React Router v7 Structure
+
+**3.1 Identify your current React Router v7 setup**
+
+React Router v7 introduced several new patterns. Look for:
+
+- \`createBrowserRouter\` with new data APIs
+- Framework mode configurations
+- Server-side rendering setup
+- New \`loader\` and \`action\` functions
+- \`defer\` usage (simplified in v7)
+- Type-safe routing features
+
+**3.2 Create root route**
+
+Create \`src/routes/__root.tsx\`:
+
+\`\`\`typescript
+import { createRootRoute, Link, Outlet } from '@tanstack/react-router'
+import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
+
+export const Route = createRootRoute({
+  component: () => (
+    <>
+      {/* Your existing layout/navbar content */}
+      <div className="p-2 flex gap-2">
+        <Link to="/" className="[&.active]:font-bold">
+          Home
+        </Link>
+        <Link to="/about" className="[&.active]:font-bold">
+          About
+        </Link>
+      </div>
+      <hr />
+      <Outlet />
+      <TanStackRouterDevtools />
+    </>
+  ),
+})
+\`\`\`
+
+**3.3 Create index route**
+
+Create \`src/routes/index.tsx\` for your home page:
+
+\`\`\`typescript
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/')({
+  component: Index,
+})
+
+function Index() {
+  return (
+    <div className="p-2">
+      <h3>Welcome Home!</h3>
+    </div>
+  )
+}
+\`\`\`
+
+**3.4 Convert React Router v7 loaders**
+
+React Router v7 simplified loader patterns. Here's how to migrate them:
+
+**React Router v7:**
+
+\`\`\`typescript
+// app/routes/posts.tsx
+export async function loader() {
+  const posts = await fetchPosts()
+  return { posts } // v7 removed need for json() wrapper
+}
+
+export default function Posts() {
+  const { posts } = useLoaderData()
+  return <div>{/* render posts */}</div>
+}
+\`\`\`
+
+**TanStack Router equivalent:**
+Create \`src/routes/posts.tsx\`:
+
+\`\`\`typescript
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/posts')({
+  loader: async () => {
+    const posts = await fetchPosts()
+    return { posts }
+  },
+  component: Posts,
+})
+
+function Posts() {
+  const { posts } = Route.useLoaderData()
+  return <div>{/* render posts */}</div>
+}
+\`\`\`
+
+**3.5 Convert dynamic routes**
+
+**React Router v7:**
+
+\`\`\`typescript
+// app/routes/posts.$postId.tsx
+export async function loader({ params }) {
+  const post = await fetchPost(params.postId)
+  return { post }
+}
+
+export default function Post() {
+  const { post } = useLoaderData()
+  return <div>{post.title}</div>
+}
+\`\`\`
+
+**TanStack Router equivalent:**
+Create \`src/routes/posts/$postId.tsx\`:
+
+\`\`\`typescript
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    const post = await fetchPost(params.postId)
+    return { post }
+  },
+  component: Post,
+})
+
+function Post() {
+  const { post } = Route.useLoaderData()
+  const { postId } = Route.useParams()
+  return <div>{post.title}</div>
+}
+\`\`\`
+
+**3.6 Convert React Router v7 actions**
+
+**React Router v7:**
+
+\`\`\`typescript
+export async function action({ request, params }) {
+  const formData = await request.formData()
+  const result = await updatePost(params.postId, formData)
+  return { success: true }
+}
+\`\`\`
+
+**TanStack Router equivalent:**
+
+\`\`\`typescript
+export const Route = createFileRoute('/posts/$postId/edit')({
+  component: EditPost,
+  // Actions are typically handled differently in TanStack Router
+  // Use mutations or form libraries like React Hook Form
+})
+
+function EditPost() {
+  const navigate = useNavigate()
+
+  const handleSubmit = async (formData) => {
+    const result = await updatePost(params.postId, formData)
+    navigate({ to: '/posts/$postId', params: { postId } })
+  }
+
+  return <form onSubmit={handleSubmit}>{/* form */}</form>
+}
+\`\`\`
+
+### Step 4: Handle React Router v7 Framework Features
+
+**4.1 Server-Side Rendering Migration**
+
+React Router v7 introduced framework mode with SSR. If you're using this:
+
+**React Router v7 Framework Mode:**
+
+\`\`\`typescript
+// react-router.config.ts
+export default {
+  ssr: true,
+  prerender: ['/'],
+}
+\`\`\`
+
+**TanStack Router approach:**
+
+TanStack Router has built-in SSR capabilities. Set up your router for SSR:
+
+\`\`\`typescript
+// src/router.tsx
+import { createRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+
+const router = createRouter({
+  routeTree,
+  context: {
+    // Add any SSR context here
+  },
+})
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router
+  }
+}
+
+export { router }
+\`\`\`
+
+For server-side rendering, use TanStack Router's built-in SSR APIs:
+
+\`\`\`typescript
+// server.tsx
+import { createMemoryHistory } from '@tanstack/react-router'
+import { StartServer } from '@tanstack/start/server'
+
+export async function render(url: string) {
+  const router = createRouter({
+    routeTree,
+    history: createMemoryHistory({ initialEntries: [url] }),
+  })
+
+  await router.load()
+
+  return (
+    <StartServer router={router} />
+  )
+}
+\`\`\`
+
+**4.2 Code Splitting Migration**
+
+React Router v7 improved code splitting. TanStack Router handles this via lazy routes:
+
+**React Router v7:**
+
+\`\`\`typescript
+const LazyComponent = lazy(() => import('./LazyComponent'))
+\`\`\`
+
+**TanStack Router:**
+
+\`\`\`typescript
+import { createLazyFileRoute } from '@tanstack/react-router'
+
+export const Route = createLazyFileRoute('/lazy-route')({
+  component: LazyComponent,
+})
+
+function LazyComponent() {
+  return <div>Lazy loaded!</div>
+}
+\`\`\`
+
+### Step 5: Update Navigation Components
+
+**5.1 Update Link components**
+
+**React Router v7:**
+
+\`\`\`typescript
+import { Link } from 'react-router'
+
+<Link to="/posts/123">View Post</Link>
+<Link to="/posts" state={{ from: 'home' }}>Posts</Link>
+\`\`\`
+
+**TanStack Router:**
+
+\`\`\`typescript
+import { Link } from '@tanstack/react-router'
+
+<Link to="/posts/$postId" params={{ postId: '123' }}>View Post</Link>
+<Link to="/posts" state={{ from: 'home' }}>Posts</Link>
+\`\`\`
+
+**5.2 Update navigation hooks**
+
+**React Router v7:**
+
+\`\`\`typescript
+import { useNavigate } from 'react-router'
+
+function Component() {
+  const navigate = useNavigate()
+
+  const handleClick = () => {
+    navigate('/posts/123')
+  }
+}
+\`\`\`
+
+**TanStack Router:**
+
+\`\`\`typescript
+import { useNavigate } from '@tanstack/react-router'
+
+function Component() {
+  const navigate = useNavigate()
+
+  const handleClick = () => {
+    navigate({ to: '/posts/$postId', params: { postId: '123' } })
+  }
+}
+\`\`\`
+
+### Step 6: Handle React Router v7 Specific Features
+
+**6.1 Migrate simplified \`defer\` usage**
+
+React Router v7 simplified defer by removing the wrapper function:
+
+**React Router v7:**
+
+\`\`\`typescript
+export async function loader() {
+  return {
+    data: fetchData(), // Promise directly returned
+  }
+}
+\`\`\`
+
+**TanStack Router:**
+
+TanStack Router uses a different approach for deferred data. Use loading states:
+
+\`\`\`typescript
+export const Route = createFileRoute('/deferred')({
+  loader: async () => {
+    const data = await fetchData()
+    return { data }
+  },
+  pendingComponent: () => <div>Loading...</div>,
+  component: DeferredComponent,
+})
+\`\`\`
+
+**6.2 Handle React Router v7's enhanced type safety**
+
+React Router v7 improved type inference. TanStack Router provides even better type safety:
+
+\`\`\`typescript
+// TanStack Router automatically infers types
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    // params.postId is automatically typed as string
+    const post = await fetchPost(params.postId)
+    return { post }
+  },
+  component: Post,
+})
+
+function Post() {
+  // post is automatically typed based on loader return
+  const { post } = Route.useLoaderData()
+  // postId is automatically typed as string
+  const { postId } = Route.useParams()
+}
+\`\`\`
+
+### Step 7: Update Your Main Router Setup
+
+**7.1 Replace React Router v7 router creation**
+
+**Before (React Router v7):**
+
+\`\`\`typescript
+import { createBrowserRouter, RouterProvider } from 'react-router'
+
+const router = createBrowserRouter([
+  // Your route definitions
+])
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <RouterProvider router={router} />
+  </React.StrictMode>,
+)
+\`\`\`
+
+**After (TanStack Router):**
+
+\`\`\`typescript
+import { RouterProvider } from '@tanstack/react-router'
+import { router } from './router'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <RouterProvider router={router} />
+  </React.StrictMode>,
+)
+\`\`\`
+
+### Step 8: Handle Search Parameters
+
+**8.1 React Router v7 to TanStack Router search params**
+
+**React Router v7:**
+
+\`\`\`typescript
+import { useSearchParams } from 'react-router'
+
+function Component() {
+  const [searchParams, setSearchParams] = useSearchParams()
+  const page = searchParams.get('page') || '1'
+
+  const updatePage = (newPage) => {
+    setSearchParams({ page: newPage })
+  }
+}
+\`\`\`
+
+**TanStack Router:**
+
+\`\`\`typescript
+import { createFileRoute } from '@tanstack/react-router'
+import { z } from 'zod'
+
+const searchSchema = z.object({
+  page: z.number().catch(1),
+  filter: z.string().optional(),
+})
+
+export const Route = createFileRoute('/posts')({
+  validateSearch: searchSchema,
+  component: Posts,
+})
+
+function Posts() {
+  const navigate = useNavigate({ from: '/posts' })
+  const { page, filter } = Route.useSearch()
+
+  const updatePage = (newPage: number) => {
+    navigate({ search: (prev) => ({ ...prev, page: newPage }) })
+  }
+}
+\`\`\`
+
+### Step 9: Remove React Router Dependencies
+
+Only after everything is working with TanStack Router:
+
+**9.1 Remove React Router v7**
+
+\`\`\`bash
+npm uninstall react-router
+\`\`\`
+
+**9.2 Clean up unused imports**
+
+Search your codebase for any remaining React Router imports:
+
+\`\`\`bash
+# Find remaining React Router imports
+grep -r "react-router" src/
+\`\`\`
+
+Remove any remaining imports and replace with TanStack Router equivalents.
+
+### Step 10: Add Advanced Type Safety
+
+**10.1 Configure strict TypeScript**
+
+Update your \`tsconfig.json\`:
+
+\`\`\`json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true
+  }
+}
+\`\`\`
+
+**10.2 Add search parameter validation**
+
+For routes with search parameters, add validation schemas:
+
+\`\`\`typescript
+import { createFileRoute } from '@tanstack/react-router'
+import { z } from 'zod'
+
+const postsSearchSchema = z.object({
+  page: z.number().min(1).catch(1),
+  search: z.string().optional(),
+  category: z.enum(['tech', 'business', 'lifestyle']).optional(),
+})
+
+export const Route = createFileRoute('/posts')({
+  validateSearch: postsSearchSchema,
+  component: Posts,
+})
+\`\`\`
+
+---
+
+## Production Checklist
+
+Before deploying your migrated application:
+
+### Router Configuration
+
+- [ ] Router instance created and properly exported
+- [ ] Route tree generated successfully
+- [ ] TypeScript declarations registered
+- [ ] All route files follow naming conventions
+
+### Route Migration
+
+- [ ] All React Router v7 routes converted to file-based routing
+- [ ] Dynamic routes updated with proper parameter syntax
+- [ ] Nested routes maintain hierarchy
+- [ ] Index routes created where needed
+- [ ] Layout routes preserve component structure
+
+### Feature Migration
+
+- [ ] All React Router v7 loaders converted
+- [ ] Actions migrated to appropriate patterns
+- [ ] Server-side rendering configured (if applicable)
+- [ ] Code splitting implemented
+- [ ] Type safety enhanced
+
+### Navigation Updates
+
+- [ ] All Link components updated to TanStack Router
+- [ ] useNavigate hooks replaced and tested
+- [ ] Navigation parameters properly typed
+- [ ] Search parameter validation implemented
+
+### Code Cleanup
+
+- [ ] React Router v7 dependencies removed
+- [ ] Unused imports cleaned up
+- [ ] No React Router references remain
+- [ ] TypeScript compilation successful
+- [ ] All tests passing
+
+### Testing
+
+- [ ] All routes accessible and rendering correctly
+- [ ] Navigation between routes working
+- [ ] Back/forward browser buttons functional
+- [ ] Search parameters persisting correctly
+- [ ] Dynamic routes with parameters working
+- [ ] Nested route layouts displaying properly
+- [ ] Framework features (SSR, code splitting) working if applicable
+
+---
+
+## Common Problems
+
+### Error: "Cannot use useNavigate outside of context"
+
+**Problem:** You have remaining React Router imports that conflict with TanStack Router.
+
+**Solution:**
+
+1. Search for all React Router imports:
+   \`\`\`bash
+   grep -r "react-router" src/
+   \`\`\`
+2. Replace all imports with TanStack Router equivalents
+3. Ensure React Router is completely uninstalled
+
+### TypeScript Errors: Route Parameters
+
+**Problem:** TypeScript showing errors about route parameters not being typed correctly.
+
+**Solution:**
+
+1. Ensure your router is registered in the TypeScript module declaration:
+   \`\`\`typescript
+   declare module '@tanstack/react-router' {
+     interface Register {
+       router: typeof router
+     }
+   }
+   \`\`\`
+2. Check that your route files export the Route correctly
+3. Verify parameter names match between route definition and usage
+
+### React Router v7 Framework Features Not Working
+
+**Problem:** Missing SSR or code splitting functionality after migration.
+
+**Solution:**
+
+1. TanStack Router has built-in SSR capabilities - use TanStack Start for full-stack applications
+2. Use TanStack Router's lazy routes for code splitting
+3. Configure SSR using TanStack Router's native APIs
+4. Follow the [SSR setup guide](../setup-ssr.md) for detailed instructions
+
+### Routes Not Matching
+
+**Problem:** Routes not rendering or 404 errors for valid routes.
+
+**Solution:**
+
+1. Check file naming follows TanStack Router conventions:
+   - Dynamic routes: \`$paramName.tsx\`
+   - Index routes: \`index.tsx\`
+   - Nested routes: proper directory structure
+2. Verify route tree generation is working
+3. Check that the router plugin is properly configured
+
+### React Router v7 Simplified APIs Not Translating
+
+**Problem:** v7's simplified \`defer\` or other features don't have direct equivalents.
+
+**Solution:**
+
+1. Use TanStack Router's pending states for loading UX
+2. Implement data fetching patterns that fit TanStack Router's architecture
+3. Leverage TanStack Router's superior type safety for better DX
+
+---
+
+## React Router v7 vs TanStack Router Feature Comparison
+
+| Feature            | React Router v7     | TanStack Router              |
+| ------------------ | ------------------- | ---------------------------- |
+| Type Safety        | Good                | Excellent                    |
+| File-based Routing | Framework mode only | Built-in                     |
+| Search Params      | Basic               | Validated with schemas       |
+| Code Splitting     | Good                | Excellent with lazy routes   |
+| SSR                | Framework mode      | Built-in with TanStack Start |
+| Bundle Size        | Larger              | Smaller                      |
+| Learning Curve     | Moderate            | Moderate                     |
+| Community          | Large               | Growing                      |
+
+---
+
+## Common Next Steps
+
+After successfully migrating to TanStack Router, consider these enhancements:
+
+### Advanced Features to Explore
+
+- **Route-based code splitting** - Improve performance with lazy loading
+- **Search parameter validation** - Type-safe URL state management
+- **Route preloading** - Enhance perceived performance
+- **Route masking** - Advanced URL management
+- **Integration with TanStack Query** - Powerful data fetching
+
+---
+
+## Related Resources
+
+- [TanStack Router Documentation](https://tanstack.com/router) - Complete API reference
+- [File-Based Routing Guide](../../routing/file-based-routing.md) - Detailed routing concepts
+- [Navigation Guide](../../guide/navigation.md) - Complete navigation patterns
+- [Search Parameters Guide](../../guide/search-params.md) - Advanced search param usage
+- [Type Safety Guide](../../guide/type-safety.md) - TypeScript integration details
+- [React Router v7 Changelog](https://reactrouter.com/start/changelog) - What changed in v7
 
 # Migration from React Location
 
@@ -895,6 +1498,20 @@ If you are facing any issues or have any questions, feel free to ask for help in
 
 Welcome to the TanStack Router FAQ! Here you'll find answers to common questions about the TanStack Router. If you have a question that isn't answered here, please feel free to ask in the [TanStack Discord](https://tlinz.com/discord).
 
+## Why should you choose TanStack Router over another router?
+
+To answer this question, it's important to view the other options in the space. There are many alternatives to choose from, but only a couple that are widely adopted and actively maintained:
+
+- **Next.js** - Widely regarded as the leading framework for starting new React projects. Its design focuses on performance, development workflows, and cutting-edge technology. The framework's APIs and abstractions, while powerful, can sometimes present as non-standard. Rapid growth and industry adoption have resulted in a feature-rich experience, sometimes leading to a steeper learning curve and increased overhead.
+- **Remix / React Router** - Based on the historically successful React Router, Remix delivers a powerful developer and user experience. Its API and architectural vision are firmly rooted in web standards such as Request/Response, with an emphasis on adaptability across various JavaScript environments. Many of its APIs and abstractions are well-designed and have influenced more than a few of TanStack Router's APIs. However, its rigid design, the integration of type safety as an add-on, and sometimes strict adherence to platform APIs can present limitations for some developers.
+
+These frameworks and routers have their strengths, but they also come with trade-offs that may not align with every project's needs. TanStack Router aims to strike a balance by offering routing APIs designed to improve the developer experience without sacrificing flexibility or performance.
+
+## Is TanStack Router a framework?
+
+TanStack Router itself is not a "framework" in the traditional sense, since it doesn't address a few other common full-stack concerns. However, TanStack Router has been designed to be upgradable to a full-stack framework when used in conjunction with other tools that address bundling, deployments, and server-side-specific functionality. This is why we are currently developing [TanStack Start](https://tanstack.com/start), a full-stack framework that is built on top of TanStack Router and Vite.
+For a deeper dive on the history of TanStack Router, feel free to read [TanStack Router's History](../decisions-on-dx.md#tanstack-routers-origin-story).
+
 ## Should I commit my \`routeTree.gen.ts\` file into git?
 
 Yes! Although the route tree file (i.e., \`routeTree.gen.ts\`) is generated by TanStack Router, it is essentially part of your application’s runtime, not a build artifact. The route tree file is a critical part of your application’s source code, and it is used by TanStack Router to build your application’s routes at runtime.