@tanstack/react-router 1.133.3 → 1.133.7

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

@@ -187,20 +187,20 @@ To install TanStack Router in your project, run the following command using your
 [//]: # 'installCommand'
 
 \`\`\`sh
-npm install @tanstack/router
+npm install @tanstack/react-router
 # or
-pnpm add @tanstack/router
+pnpm add @tanstack/react-router
 #or
-yarn add @tanstack/router
+yarn add @tanstack/react-router
 # or
-bun add @tanstack/router
+bun add @tanstack/react-router
 # or
-deno add npm:@tanstack/router
+deno add npm:@tanstack/react-router
 \`\`\`
 
 [//]: # 'installCommand'
 
-Once installed, you can verify the installation by checking your \`package.json\` file for the \`@tanstack/router\` dependency.
+Once installed, you can verify the installation by checking your \`package.json\` file for the dependency.
 
 [//]: # 'packageJson'
 
@@ -295,6 +295,242 @@ npm run dev
 
 With either approach, you can now start building your React application with TanStack Router!
 
+# Decisions on Developer Experience
+
+When people first start using TanStack Router, they often have a lot of questions that revolve around the following themes:
+
+> Why do I have to do things this way?
+
+> Why is it done this way? and not that way?
+
+> I'm used to doing it this way, why should I change?
+
+And they are all valid questions. For the most part, people are used to using routing libraries that are very similar to each other. They all have a similar API, similar concepts, and similar ways of doing things.
+
+But TanStack Router is different. It's not your average routing library. It's not your average state management library. It's not your average anything.
+
+## TanStack Router's origin story
+
+It's important to remember that TanStack Router's origins stem from [Nozzle.io](https://nozzle.io)'s need for a client-side routing solution that offered a first-in-class _URL Search Parameters_ experience without compromising on the **_type-safety_** that was required to power its complex dashboards.
+
+And so, from TanStack Router's very inception, every facet of its design was meticulously thought out to ensure that its type-safety and developer experience were second to none.
+
+## How does TanStack Router achieve this?
+
+> TypeScript! TypeScript! TypeScript!
+
+Every aspect of TanStack Router is designed to be as type-safe as possible, and this is achieved by leveraging TypeScript's type system to its fullest extent. This involves using some very advanced and complex types, type inference, and other features to ensure that the developer experience is as smooth as possible.
+
+But to achieve this, we had to make some decisions that deviate from the norms in the routing world.
+
+1. [**Route configuration boilerplate?**](#1-why-is-the-routers-configuration-done-this-way): You have to define your routes in a way that allows TypeScript to infer the types of your routes as much as possible.
+2. [**TypeScript module declaration for the router?**](#2-declaring-the-router-instance-for-type-inference): You have to pass the \`Router\` instance to the rest of your application using TypeScript's module declaration.
+3. [**Why push for file-based routing over code-based?**](#3-why-is-file-based-routing-the-preferred-way-to-define-routes): We push for file-based routing as the preferred way to define your routes.
+
+> TLDR; All the design decisions in the developer experience of using TanStack Router are made so that you can have a best-in-class type-safety experience without compromising on the control, flexibility, and maintainability of your route configurations.
+
+## 1. Why is the Router's configuration done this way?
+
+When you want to leverage the TypeScript's inference features to its fullest, you'll quickly realize that _Generics_ are your best friend. And so, TanStack Router uses Generics everywhere to ensure that the types of your routes are inferred as much as possible.
+
+This means that you have to define your routes in a way that allows TypeScript to infer the types of your routes as much as possible.
+
+> Can I use JSX to define my routes?
+
+Using JSX for defining your routes is **out of the question**, as TypeScript will not be able to infer the route configuration types of your router.
+
+\`\`\`tsx
+// ⛔️ This is not possible
+function App() {
+  return (
+    <Router>
+      <Route path="/posts" component={PostsPage} />
+      <Route path="/posts/$postId" component={PostIdPage} />
+      {/* ... */}
+    </Router>
+    // ^? TypeScript cannot infer the routes in this configuration
+  )
+}
+\`\`\`
+
+And since this would mean that you'd have to manually type the \`to\` prop of the \`<Link>\` component and wouldn't catch any errors until runtime, it's not a viable option.
+
+> Maybe I could define my routes as a tree of nested objects?
+
+\`\`\`tsx
+// ⛔️ This file will just keep growing and growing...
+const router = createRouter({
+  routes: {
+    posts: {
+      component: PostsPage, // /posts
+      children: {
+        $postId: {
+          component: PostIdPage, // /posts/$postId
+        },
+      },
+    },
+    // ...
+  },
+})
+\`\`\`
+
+At first glance, this seems like a good idea. It's easy to visualize the entire route hierarchy in one go. But this approach has a couple of big downsides that make it not ideal for large applications:
+
+- **It's not very scalable**: As your application grows, the tree will grow and become harder to manage. And since it's all defined in one file, it can become very hard to maintain.
+- **It's not great for code-splitting**: You'd have to manually code-split each component and then pass it into the \`component\` property of the route, further complicating the route configuration with an ever-growing route configuration file.
+
+This only gets worse as you begin to use more features of the router, such as nested context, loaders, search param validation, etc.
+
+> So, what's the best way to define my routes?
+
+What we found to be the best way to define your routes is to abstract the definition of the route configuration outside of the route-tree. Then stitch together your route configurations into a single cohesive route-tree that is then passed into the \`createRouter\` function.
+
+You can read more about [code-based routing](../routing/code-based-routing.md) to see how to define your routes in this way.
+
+> [!TIP]
+> Finding Code-based routing to be a bit too cumbersome? See why [file-based routing](#3-why-is-file-based-routing-the-preferred-way-to-define-routes) is the preferred way to define your routes.
+
+## 2. Declaring the Router instance for type inference
+
+> Why do I have to declare the \`Router\`?
+
+> This declaration stuff is way too complicated for me...
+
+Once you've constructed your routes into a tree and passed it into your Router instance (using \`createRouter\`) with all the generics working correctly, you then need to somehow pass this information to the rest of your application.
+
+There were two approaches we considered for this:
+
+1. **Imports**: You could import the \`Router\` instance from the file where you created it and use it directly in your components.
+
+\`\`\`tsx
+import { router } from '@/src/app'
+export const PostsIdLink = () => {
+  return (
+    <Link<typeof router> to="/posts/$postId" params={{ postId: '123' }}>
+      Go to post 123
+    </Link>
+  )
+}
+\`\`\`
+
+A downside to this approach is that you'd have to import the entire \`Router\` instance into every file where you want to use it. This can lead to increased bundle sizes and can be cumbersome to manage, and only get worse as your application grows and you use more features of the router.
+
+2. **Module declaration**: You can use TypeScript's module declaration to declare the \`Router\` instance as a module that can be used for type inference anywhere in your application without having to import it.
+
+You'll do this once in your application.
+
+\`\`\`tsx
+// src/app.tsx
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router
+  }
+}
+\`\`\`
+
+And then you can benefit from its auto-complete anywhere in your app without having to import it.
+
+\`\`\`tsx
+export const PostsIdLink = () => {
+  return (
+    <Link
+      to="/posts/$postId"
+      // ^? TypeScript will auto-complete this for you
+      params={{ postId: '123' }} // and this too!
+    >
+      Go to post 123
+    </Link>
+  )
+}
+\`\`\`
+
+We went with **module declaration**, as it is what we found to be the most scalable and maintainable approach with the least amount of overhead and boilerplate.
+
+## 3. Why is file-based routing the preferred way to define routes?
+
+> Why are the docs pushing for file-based routing?
+
+> I'm used to defining my routes in a single file, why should I change?
+
+Something you'll notice (quite soon) in the TanStack Router documentation is that we push for **file-based routing** as the preferred method for defining your routes. This is because we've found that file-based routing is the most scalable and maintainable way to define your routes.
+
+> [!TIP]
+> Before you continue, it's important you have a good understanding of [code-based routing](../routing/code-based-routing.md) and [file-based routing](../routing/file-based-routing.md).
+
+As mentioned in the beginning, TanStack Router was designed for complex applications that require a high degree of type-safety and maintainability. And to achieve this, the configuration of the router has been done in a precise way that allows TypeScript to infer the types of your routes as much as possible.
+
+A key difference in the set-up of a _basic_ application with TanStack Router, is that your route configurations require a function to be provided to \`getParentRoute\`, that returns the parent route of the current route.
+
+\`\`\`tsx
+import { createRoute } from '@tanstack/react-router'
+import { postsRoute } from './postsRoute'
+
+export const postsIndexRoute = createRoute({
+  getParentRoute: () => postsRoute,
+  path: '/',
+})
+\`\`\`
+
+At this stage, this is done so the definition of \`postsIndexRoute\` can be aware of its location in the route tree and so that it can correctly infer the types of the \`context\`, \`path params\`, \`search params\` returned by the parent route. Incorrectly defining the \`getParentRoute\` function means that the properties of the parent route will not be correctly inferred by the child route.
+
+As such, this is a critical part of the route configuration and a point of failure if not done correctly.
+
+But this is only one part of setting up a basic application. TanStack Router requires all the routes (including the root route) to be stitched into a **_route-tree_** so that it may be passed into the \`createRouter\` function before declaring the \`Router\` instance on the module for type inference. This is another critical part of the route configuration and a point of failure if not done correctly.
+
+> 🤯 If this route-tree were in its own file for an application with ~40-50 routes, it can easily grow up to 700+ lines.
+
+\`\`\`tsx
+const routeTree = rootRoute.addChildren([
+  postsRoute.addChildren([postsIndexRoute, postsIdRoute]),
+])
+\`\`\`
+
+This complexity only increases as you begin to use more features of the router, such as nested context, loaders, search param validation, etc. As such, it no longer becomes feasible to define your routes in a single file. And so, users end up building their own _semi consistent_ way of defining their routes across multiple files. This can lead to inconsistencies and errors in the route configuration.
+
+Finally, comes the issue of code-splitting. As your application grows, you'll want to code-split your components to reduce the initial bundle size of your application. This can be a bit of a headache to manage when you're defining your routes in a single file or even across multiple files.
+
+\`\`\`tsx
+import { createRoute, lazyRouteComponent } from '@tanstack/react-router'
+import { postsRoute } from './postsRoute'
+
+export const postsIndexRoute = createRoute({
+  getParentRoute: () => postsRoute,
+  path: '/',
+  component: lazyRouteComponent(() => import('../page-components/posts/index')),
+})
+\`\`\`
+
+All of this boilerplate, no matter how essential for providing a best-in-class type-inference experience, can be a bit overwhelming and can lead to inconsistencies and errors in the route configuration.
+
+... and this example configuration is just for rendering a single codes-split route. Imagine having to do this for 40-50 routes. Now remember that you still haven't touched the \`context\`, \`loaders\`, \`search param validation\`, and other features of the router 🤕.
+
+> So, why's file-based routing the preferred way?
+
+TanStack Router's file-based routing is designed to solve all of these issues. It allows you to define your routes in a predictable way that is easy to manage and maintain, and is scalable as your application grows.
+
+The file-based routing approach is powered by the TanStack Router Bundler Plugin. It performs 3 essential tasks that solve the pain points in route configuration when using code-based routing:
+
+1. **Route configuration boilerplate**: It generates the boilerplate for your route configurations.
+2. **Route tree stitching**: It stitches together your route configurations into a single cohesive route-tree. Also in the background, it correctly updates the route configurations to define the \`getParentRoute\` function match the routes with their parent routes.
+3. **Code-splitting**: It automatically code-splits your route content components and updates the route configurations with the correct component. Additionally, at runtime, it ensures that the correct component is loaded when the route is visited.
+
+Let's take a look at how the route configuration for the previous example would look like with file-based routing.
+
+\`\`\`tsx
+// src/routes/posts/index.ts
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/posts/')({
+  component: () => 'Posts index component goes here!!!',
+})
+\`\`\`
+
+That's it! No need to worry about defining the \`getParentRoute\` function, stitching together the route-tree, or code-splitting your components. The TanStack Router Bundler Plugin handles all of this for you.
+
+At no point does the TanStack Router Bundler Plugin take away your control over your route configurations. It's designed to be as flexible as possible, allowing you to define your routes in a way that suits your application whilst reducing the boilerplate and complexity of the route configuration.
+
+Check out the guides for [file-based routing](../routing/file-based-routing.md) and [code-splitting](../guide/code-splitting.md) for a more in-depth explanation of how they work in TanStack Router.
+
 # Devtools
 
 > Link, take this sword... I mean Devtools!... to help you on your way!
@@ -485,1015 +721,6 @@ 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.
 
-# 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
-
-Before you begin your journey in migrating from React Location, it's important that you have a good understanding of the [Routing Concepts](../routing/routing-concepts.md) and [Design Decisions](../decisions-on-dx.md) used by TanStack Router.
-
-## Differences between React Location and TanStack Router
-
-React Location and TanStack Router share much of same design decisions concepts, but there are some key differences that you should be aware of.
-
-- React Location uses _generics_ to infer types for routes, while TanStack Router uses _module declaration merging_ to infer types.
-- Route configuration in React Location is done using a single array of route definitions, while in TanStack Router, route configuration is done using a tree of route definitions starting with the [root route](../routing/routing-concepts.md#the-root-route).
-- [File-based routing](../routing/file-based-routing.md) is the recommended way to define routes in TanStack Router, while React Location only allows you to define routes in a single file using a code-based approach.
-  - TanStack Router does support a [code-based approach](../routing/code-based-routing.md) to defining routes, but it is not recommended for most use cases. You can read more about why, over here: [why is file-based routing the preferred way to define routes?](../decisions-on-dx.md#3-why-is-file-based-routing-the-preferred-way-to-define-routes)
-
-## Migration guide
-
-In this guide we'll go over the process of migrating the [React Location Basic example](https://github.com/TanStack/router/tree/react-location/examples/basic) over to TanStack Router using file-based routing, with the end goal of having the same functionality as the original example (styling and other non-routing related code will be omitted).
-
-> [!TIP]
-> To use a code-based approach for defining your routes, you can read the [code-based Routing](../routing/code-based-routing.md) guide.
-
-### Step 1: Swap over to TanStack Router's dependencies
-
-First, we need to install the dependencies for TanStack Router. For detailed installation instructions, see our [How to Install TanStack Router](../how-to/install.md) guide.
-
-\`\`\`sh
-npm install @tanstack/react-router @tanstack/router-devtools
-\`\`\`
-
-And remove the React Location dependencies.
-
-\`\`\`sh
-npm uninstall @tanstack/react-location @tanstack/react-location-devtools
-\`\`\`
-
-### Step 2: Use the file-based routing watcher
-
-If your project uses Vite (or one of the supported bundlers), you can use the TanStack Router plugin to watch for changes in your routes files and automatically update the routes configuration.
-
-Installation of the Vite plugin:
-
-\`\`\`sh
-npm install -D @tanstack/router-plugin
-\`\`\`
-
-And add it to your \`vite.config.js\`:
-
-\`\`\`js
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import { tanstackRouter } from '@tanstack/router-plugin/vite'
-
-export default defineConfig({
-  // ...
-  plugins: [tanstackRouter(), react()],
-})
-\`\`\`
-
-However, if your application does not use Vite, you use one of our other [supported bundlers](../routing/file-based-routing.md#getting-started-with-file-based-routing), or you can use the \`@tanstack/router-cli\` package to watch for changes in your routes files and automatically update the routes configuration.
-
-### Step 3: Add the file-based configuration file to your project
-
-Create a \`tsr.config.json\` file in the root of your project with the following content:
-
-\`\`\`json
-{
-  "routesDirectory": "./src/routes",
-  "generatedRouteTree": "./src/routeTree.gen.ts"
-}
-\`\`\`
-
-You can find the full list of options for the \`tsr.config.json\` file [here](../../../api/file-based-routing.md).
-
-### Step 4: Create the routes directory
-
-Create a \`routes\` directory in the \`src\` directory of your project.
-
-\`\`\`sh
-mkdir src/routes
-\`\`\`
-
-### Step 5: Create the root route file
-
-\`\`\`tsx
-// src/routes/__root.tsx
-import { createRootRoute, Outlet, Link } from '@tanstack/react-router'
-import { TanStackRouterDevtools } from '@tanstack/router-devtools'
-
-export const Route = createRootRoute({
-  component: () => {
-    return (
-      <>
-        <div>
-          <Link to="/" activeOptions={{ exact: true }}>
-            Home
-          </Link>
-          <Link to="/posts">Posts</Link>
-        </div>
-        <hr />
-        <Outlet />
-        <TanStackRouterDevtools />
-      </>
-    )
-  },
-})
-\`\`\`
-
-### Step 6: Create the index route file
-
-\`\`\`tsx
-// src/routes/index.tsx
-import { createFileRoute } from '@tanstack/react-router'
-
-export const Route = createFileRoute('/')({
-  component: Index,
-})
-\`\`\`
-
-> You will need to move any related components and logic needed for the index route from the \`src/index.tsx\` file to the \`src/routes/index.tsx\` file.
-
-### Step 7: Create the posts route file
-
-\`\`\`tsx
-// src/routes/posts.tsx
-import { createFileRoute, Link, Outlet } from '@tanstack/react-router'
-
-export const Route = createFileRoute('/posts')({
-  component: Posts,
-  loader: async () => {
-    const posts = await fetchPosts()
-    return {
-      posts,
-    }
-  },
-})
-
-function Posts() {
-  const { posts } = Route.useLoaderData()
-  return (
-    <div>
-      <nav>
-        {posts.map((post) => (
-          <Link
-            key={post.id}
-            to={\`/posts/$postId\`}
-            params={{ postId: post.id }}
-          >
-            {post.title}
-          </Link>
-        ))}
-      </nav>
-      <Outlet />
-    </div>
-  )
-}
-\`\`\`
-
-> You will need to move any related components and logic needed for the posts route from the \`src/index.tsx\` file to the \`src/routes/posts.tsx\` file.
-
-### Step 8: Create the posts index route file
-
-\`\`\`tsx
-// src/routes/posts.index.tsx
-import { createFileRoute } from '@tanstack/react-router'
-
-export const Route = createFileRoute('/posts/')({
-  component: PostsIndex,
-})
-\`\`\`
-
-> You will need to move any related components and logic needed for the posts index route from the \`src/index.tsx\` file to the \`src/routes/posts.index.tsx\` file.
-
-### Step 9: Create the posts id route file
-
-\`\`\`tsx
-// src/routes/posts.$postId.tsx
-import { createFileRoute } from '@tanstack/react-router'
-
-export const Route = createFileRoute('/posts/$postId')({
-  component: PostsId,
-  loader: async ({ params: { postId } }) => {
-    const post = await fetchPost(postId)
-    return {
-      post,
-    }
-  },
-})
-
-function PostsId() {
-  const { post } = Route.useLoaderData()
-  // ...
-}
-\`\`\`
-
-> You will need to move any related components and logic needed for the posts id route from the \`src/index.tsx\` file to the \`src/routes/posts.$postId.tsx\` file.
-
-### Step 10: Generate the route tree
-
-If you are using one of the supported bundlers, the route tree will be generated automatically when you run the dev script.
-
-If you are not using one of the supported bundlers, you can generate the route tree by running the following command:
-
-\`\`\`sh
-npx tsr generate
-\`\`\`
-
-### Step 11: Update the main entry file to render the Router
-
-Once you've generated the route-tree, you can then update the \`src/index.tsx\` file to create the router instance and render it.
-
-\`\`\`tsx
-// src/index.tsx
-import React from 'react'
-import ReactDOM from 'react-dom'
-import { createRouter, RouterProvider } from '@tanstack/react-router'
-
-// Import the generated route tree
-import { routeTree } from './routeTree.gen'
-
-// 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
-  }
-}
-
-const domElementId = 'root' // Assuming you have a root element with the id 'root'
-
-// Render the app
-const rootElement = document.getElementById(domElementId)
-if (!rootElement) {
-  throw new Error(\`Element with id \${domElementId} not found\`)
-}
-
-ReactDOM.createRoot(rootElement).render(
-  <React.StrictMode>
-    <RouterProvider router={router} />
-  </React.StrictMode>,
-)
-\`\`\`
-
-### Finished!
-
-You should now have successfully migrated your application from React Location to TanStack Router using file-based routing.
-
-React Location also has a few more features that you might be using in your application. Here are some guides to help you migrate those features:
-
-- [Search params](../guide/search-params.md)
-- [Data loading](../guide/data-loading.md)
-- [History types](../guide/history-types.md)
-- [Wildcard / Splat / Catch-all routes](../routing/routing-concepts.md#splat--catch-all-routes)
-- [Authenticated routes](../guide/authenticated-routes.md)
-
-TanStack Router also has a few more features that you might want to explore:
-
-- [Router Context](../guide/router-context.md)
-- [Preloading](../guide/preloading.md)
-- [Pathless Layout Routes](../routing/routing-concepts.md#pathless-layout-routes)
-- [Route masking](../guide/route-masking.md)
-- [SSR](../guide/ssr.md)
-- ... and more!
-
-If you are facing any issues or have any questions, feel free to ask for help in the TanStack Discord.
-
 # Frequently Asked Questions
 
 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).