TanStack Router

https://tanstack.com/router/latest/docs/
Admin
TanStack Router is a modern, type-safe routing library for React applications that provides powerful...
Tokens:170,104
Snippets:1,634
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Solid Router Devtools

Source: https://tanstack.com/router/latest/docs/devtools.md

Install the Solid devtools package using npm or yarn.

```bash
npm install @tanstack/solid-router-devtools
yarn add @tanstack/solid-router-devtools
```

--------------------------------

### Install Auth0 SDK

Source: https://tanstack.com/router/latest/docs/how-to/setup-auth-providers.md

Install the required Auth0 React SDK package.

```bash
npm install @auth0/auth0-react
```

--------------------------------

### Recommended Legacy Config Setup

Source: https://tanstack.com/router/latest/docs/eslint/eslint-plugin-router.md

Enable all recommended rules using the legacy .eslintrc format.

```json
{
  "extends": ["plugin:@tanstack/eslint-plugin-router/recommended"]
}
```

--------------------------------

### Install React Router Devtools

Source: https://tanstack.com/router/latest/docs/devtools.md

Install the React devtools package using npm or yarn.

```bash
npm install @tanstack/react-router-devtools
yarn add @tanstack/react-router-devtools
```

--------------------------------

### Verify Installation

Source: https://tanstack.com/router/latest/docs/how-to/install.md

Check your package.json file to ensure the dependency is correctly listed.

```json
{
  "dependencies": {
    "@tanstack/react-router": "^x.x.x"
  }
}
```

--------------------------------

### Install Supabase dependency

Source: https://tanstack.com/router/latest/docs/how-to/setup-auth-providers.md

Install the official Supabase JavaScript client library.

```bash
npm install @supabase/supabase-js
```

--------------------------------

### Recommended Flat Config Setup

Source: https://tanstack.com/router/latest/docs/eslint/eslint-plugin-router.md

Enable all recommended rules for the plugin using the flat config format.

```js
import pluginRouter from '@tanstack/eslint-plugin-router'

export default [
  ...pluginRouter.configs['flat/recommended'],
  // Any other config...
]
```

--------------------------------

### Install TanStack Router dependencies

Source: https://tanstack.com/router/latest/docs/installation/migrate-from-react-location.md

Install the core router and devtools packages.

```sh
npm install @tanstack/react-router @tanstack/router-devtools
```

--------------------------------

### Example search string output

Source: https://tanstack.com/router/latest/docs/guide/custom-search-param-serialization.md

The resulting search string format when using query-string configuration.

```txt
?page=1&sort=asc&filters=author%3Dtanner%26min_words%3D800
```

--------------------------------

### Equivalent route filenames

Source: https://tanstack.com/router/latest/docs/api/file-based-routing.md

Examples of different file naming conventions that resolve to the same runtime URL.

```txt
src/routes/posts.tsx -> /posts
src/routes/posts.route.tsx -> /posts
src/routes/posts/route.tsx -> /posts
```

--------------------------------

### Setup TanStack Query Integration

Source: https://tanstack.com/router/latest/docs/integrations/query.md

Initialize the router and wire up the integration with a fresh QueryClient per request.

```tsx
import { QueryClient } from '@tanstack/react-query'
import { createRouter } from '@tanstack/react-router'
import { setupRouterSsrQueryIntegration } from '@tanstack/react-router-ssr-query'
import { routeTree } from './routeTree.gen'

export function getRouter() {
  const queryClient = new QueryClient()
  const router = createRouter({
    routeTree,
    // optionally expose the QueryClient via router context
    context: { queryClient },
    scrollRestoration: true,
    defaultPreload: 'intent',
  })

  setupRouterSsrQueryIntegration({
    router,
    queryClient,
    // optional:
    // handleRedirects: true,
    // wrapQueryClient: true,
  })

  return router
}
```

--------------------------------

### Link Active Matching Examples

Source: https://tanstack.com/router/latest/docs/guide/navigation.md

Examples of how different link configurations match against the current route.

```tsx
const link1 = (
  <Link to="/blog/post/$postId" params={{ postId: 'my-first-blog-post' }}>
    Blog Post
  </Link>
)
const link2 = <Link to="/blog/post">Blog Post</Link>
const link3 = <Link to="/blog">Blog Post</Link>
```

```tsx
const link4 = (
  <Link to="/blog/post/$postId" params={{ postId: 'my-second-blog-post' }}>
    Blog Post
  </Link>
)
```

--------------------------------

### Implement Location Masking with TanStack Router

Source: https://tanstack.com/router/latest/docs/framework/react/examples/location-masking

This example shows the setup for a root route, data fetching, and modal rendering using Radix UI and TanStack Router.

```typescript
import React from 'react'
import ReactDOM from 'react-dom/client'
import {
  ErrorComponent,
  Link,
  Outlet,
  RouterProvider,
  createRootRoute,
  createRoute,
  createRouteMask,
  createRouter,
  useNavigate,
  useRouterState,
} from '@tanstack/react-router'
import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
import * as Dialog from '@radix-ui/react-dialog'
import type { ErrorComponentProps } from '@tanstack/react-router'
import './styles.css'

type PhotoType = {
  id: string
  title: string
  url: string
  thumbnailUrl: string
  albumId: string
}

class NotFoundError extends Error {}

const fetchPhotos = async () => {
  console.info('Fetching photos...')
  await new Promise((r) => setTimeout(r, 500))
  // Generate mock photos using picsum.photos since via.placeholder.com is down
  return Array.from({ length: 10 }, (_, i) => ({
    id: String(i + 1),
    title: `Photo ${i + 1}`,
    url: `https://picsum.photos/600/400?random=${i + 1}`,
    thumbnailUrl: `https://picsum.photos/200/200?random=${i + 1}`,
    albumId: '1',
  }))
}

const fetchPhoto = async (photoId: string) => {
  console.info(`Fetching photo with id ${photoId}...`)
  await new Promise((r) => setTimeout(r, 500))

  // Simulate photo not found for invalid IDs
  const photoIdNum = parseInt(photoId, 10)
  if (isNaN(photoIdNum) || photoIdNum < 1 || photoIdNum > 10) {
    throw new NotFoundError(`Photo with id "${photoId}" not found!`)
  }

  // Generate mock photo using picsum.photos
  return {
    id: photoId,
    title: `Photo ${photoId}`,
    url: `https://picsum.photos/600/400?random=${photoId}`,
    thumbnailUrl: `https://picsum.photos/200/200?random=${photoId}`,
    albumId: '1',
  }
}

type PhotoModal = {
  id: 'photo'
  photoId: string
}

type ModalObject = PhotoModal

export function Spinner() {
  return (
    <div className="animate-spin px-3 text-xl inline-flex items-center justify-center">
      ⍥
    </div>
  )
}

const rootRoute = createRootRoute({
  validateSearch: (search) =>
    search as {
      modal?: ModalObject
    },
  component: RootComponent,
})

function RootComponent() {
  const status = useRouterState({ select: (s) => s.status })

  return (
    <>
      <div className="p-2 flex gap-2 text-lg">
        <Link
          to="/"
          activeProps={{
            className: 'font-bold',
          }}
          activeOptions={{ exact: true }}
        >
          Home
        </Link>{' '}
        <Link
          to="/photos"
          activeProps={{
            className: 'font-bold',
          }}
        >
          Photos
        </Link>{' '}
        {status === 'pending' ? <Spinner /> : null}
      </div>
      <hr />
      <Outlet />
      {/* Start rendering router matches */}
      <TanStackRouterDevtools position="bottom-right" />
    </>
  )
}

function Modal(props: Dialog.DialogProps) {
  return (
    <Dialog.Root open {...props}>
      <Dialog.Portal>
        <Dialog.Overlay className="fixed inset-0 bg-black/70" />
        <Dialog.DialogContent className="fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2">
          {props.children}
        </Dialog.DialogContent>
      </Dialog.Portal>
    </Dialog.Root>
  )
}

const indexRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/',
  component: () => {
    return (
      <div className="p-2">
        <h3>Welcome Home!</h3>
      </div>
    )
  },
})
const photosLayoutRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: 'photos',
  loader: fetchPhotos,
  component: PhotosRoute,
})

function PhotosRoute() {
  const photos = photosLayoutRoute.useLoaderData()
```

--------------------------------

### Example File System Structure

Source: https://tanstack.com/router/latest/docs/routing/virtual-file-routes.md

A visual representation of a project structure mixing file-based and virtual routing conventions.

```text
â”œâ”€â”€ __root.tsx
â”œâ”€â”€ index.tsx
â”œâ”€â”€ posts
â”‚   â”œâ”€â”€ __virtual.ts
â”‚   â”œâ”€â”€ details.tsx
â”‚   â”œâ”€â”€ home.tsx
â”‚   â””â”€â”€ lets-go
â”‚       â”œâ”€â”€ deeper
â”‚       â”‚   â”œâ”€â”€ __virtual.ts
â”‚       â”‚   â””â”€â”€ home.tsx
â”‚       â””â”€â”€ index.tsx
â””â”€â”€ posts.tsx
```

--------------------------------

### Install TanStack Router

Source: https://tanstack.com/router/latest/docs/installation/migrate-from-react-router.md

Command to install the TanStack Router package.

```bash
npm i @tanstack/react-router
```

--------------------------------

### Custom Legacy Config Setup

Source: https://tanstack.com/router/latest/docs/eslint/eslint-plugin-router.md

Manually configure specific rules in the legacy .eslintrc format.

```json
{
  "plugins": ["@tanstack/eslint-plugin-router"],
  "rules": {
    "@tanstack/router/create-route-property-order": "error"
  }
}
```

--------------------------------

### Visualize Pathless Layout Directory Structure

Source: https://tanstack.com/router/latest/docs/routing/routing-concepts.md

Example of a file-based routing structure using a pathless layout.

```text
routes/
â”œâ”€â”€ _pathlessLayout/
â”‚   â”œâ”€â”€ route.tsx
â”‚   â”œâ”€â”€ a.tsx
â”‚   â”œâ”€â”€ b.tsx
```

--------------------------------

### Example route file structure with ignored components

Source: https://tanstack.com/router/latest/docs/api/file-based-routing.md

Demonstrates how the routeFileIgnorePrefix can be used to co-locate non-route files.

```txt
src/routes
â”œâ”€â”€ posts
â”‚   â”œâ”€â”€ -components  // Ignored
â”‚   â”‚   â”œâ”€â”€ Post.tsx
â”‚   â”œâ”€â”€ index.tsx
â”‚   â”œâ”€â”€ route.tsx
```

--------------------------------

### Install TanStack Router Vite plugin

Source: https://tanstack.com/router/latest/docs/installation/migrate-from-react-location.md

Add the development plugin for automatic route generation.

```sh
npm install -D @tanstack/router-plugin
```

--------------------------------

### Placeholder for Solid Link Example

Source: https://tanstack.com/router/latest/docs/guide/custom-link.md

A placeholder for a future Solid-specific link implementation.

```tsx
// TODO: Add this example.
```

--------------------------------

### Define Routes in Solid

Source: https://tanstack.com/router/latest/docs/routing/code-based-routing.md

Example of defining a hierarchy of routes using createRoute and createRootRoute in a Solid application.

```tsx
import { createRootRoute, createRoute } from '@tanstack/solid-router'

const rootRoute = createRootRoute()

const indexRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/',
})

const aboutRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: 'about',
})

const postsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: 'posts',
})

const postsIndexRoute = createRoute({
  getParentRoute: () => postsRoute,
  path: '/',
})

const postRoute = createRoute({
  getParentRoute: () => postsRoute,
  path: '$postId',
})

const postEditorRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: 'posts/$postId/edit',
})

const settingsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: 'settings',
})

const profileRoute = createRoute({
  getParentRoute: () => settingsRoute,
  path: 'profile',
})

const notificationsRoute = createRoute({
  getParentRoute: () => settingsRoute,
  path: 'notifications',
})

const pathlessLayoutRoute = createRoute({
  getParentRoute: () => rootRoute,
  id: 'pathlessLayout',
})

const pathlessLayoutARoute = createRoute({
  getParentRoute: () => pathlessLayoutRoute,
  path: 'route-a',
})

const pathlessLayoutBRoute = createRoute({
  getParentRoute: () => pathlessLayoutRoute,
  path: 'route-b',
})

const filesRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: 'files/$',
})
```

--------------------------------

### Custom Flat Config Setup

Source: https://tanstack.com/router/latest/docs/eslint/eslint-plugin-router.md

Manually configure specific rules by adding the plugin to the plugins object.

```js
import pluginRouter from '@tanstack/eslint-plugin-router'

export default [
  {
    plugins: {
      '@tanstack/router': pluginRouter,
    },
    rules: {
      '@tanstack/router/create-route-property-order': 'error',
    },
  },
  // Any other config...
]
```

--------------------------------

### Implement Kitchen Sink Routing Logic

Source: https://tanstack.com/router/latest/docs/framework/react/examples/kitchen-sink

This snippet demonstrates the setup of root routes, custom not-found components, and router state management.

```typescript
/* eslint-disable @typescript-eslint/no-unnecessary-condition */
import * as React from 'react'
import ReactDOM from 'react-dom/client'
import {
  ErrorComponent,
  Link,
  MatchRoute,
  Outlet,
  RouterProvider,
  createRootRouteWithContext,
  createRoute,
  createRouter,
  lazyRouteComponent,
  notFound,
  redirect,
  retainSearchParams,
  useNavigate,
  useRouter,
  useRouterState,
  useSearch,
} from '@tanstack/react-router'
import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
import { z } from 'zod'
import {
  fetchInvoiceById,
  fetchInvoices,
  fetchUserById,
  fetchUsers,
  patchInvoice,
  postInvoice,
} from './mockTodos'
import { useMutation } from './useMutation'
import type { NotFoundRouteProps } from '@tanstack/react-router'
import type { Invoice } from './mockTodos'
import './styles.css'

//

type UsersViewSortBy = 'name' | 'id' | 'email'

type MissingUserData = {
  userId: number
}

function isMissingUserData(data: unknown): data is MissingUserData {
  return (
    typeof data === 'object' &&
    data !== null &&
    typeof (data as { userId?: unknown }).userId === 'number'
  )
}

function UsersNotFoundComponent({ data, routeId }: NotFoundRouteProps) {
  const userId = isMissingUserData(data) ? data.userId : undefined

  return (
    <div className="p-4 space-y-2">
      <h4 className="text-lg font-bold">User not found</h4>
      <p>
        {typeof userId === 'number'
          ? `We couldn't find a user with ID ${userId}.`
          : "We couldn't find the requested user."}
      </p>
      <p className="text-xs text-gray-500">
        Rendered by the "{routeId}" route.
      </p>
      <p className="text-sm text-gray-500">
        Pick another user from the list on the left to continue.
      </p>
    </div>
  )
}

const rootRoute = createRootRouteWithContext<{
  auth: Auth
}>()({
  component: RootComponent,
})

function RouterSpinner() {
  const isLoading = useRouterState({ select: (s) => s.status === 'pending' })
  return <Spinner show={isLoading} />
}
```

--------------------------------

### Example Serialized Search String

Source: https://tanstack.com/router/latest/docs/guide/custom-search-param-serialization.md

A sample output of a search string generated using custom binary serialization.

```txt
?page=1&sort=asc&filters=JTdCJUMyJUE4YXV0aG9yJUMyJUE4JUMyJUE4dGFubmVyJUMyJUE4JUMyJUE4bWluX3dvcmRzJUMyJUE4JUMyJUEyQ3UlN0Q%3D
```

--------------------------------

### Create a file-based route with FileRoute

Source: https://tanstack.com/router/latest/docs/api/router/FileRouteClass.md

Example of initializing a route instance using FileRoute and configuring it with the createRoute method. The instance must be exported as 'Route' for the CLI tools to function correctly.

```tsx
import { FileRoute } from '@tanstack/react-router'

export const Route = new FileRoute('/').createRoute({
  loader: () => {
    return 'Hello World'
  },
  component: IndexComponent,
})

function IndexComponent() {
  const data = Route.useLoaderData()
  return <div>{data}</div>
}
```

--------------------------------

### Example JSURL2 search string output

Source: https://tanstack.com/router/latest/docs/guide/custom-search-param-serialization.md

The resulting search string format when using JSURL2 configuration.

```txt
?page=1&sort=asc&filters=(author~tanner~min*_words~800)~
```

--------------------------------

### Example Serialized Search String

Source: https://tanstack.com/router/latest/docs/guide/custom-search-param-serialization.md

A sample output of a search string serialized using the binary encoding method.

```txt
?page=1&sort=asc&filters=eyJhdXRob3IiOiJ0YW5uZXIiLCJtaW5fd29yZHMiOjgwMH0%3D
```

--------------------------------

### File-Based Route Structure

Source: https://tanstack.com/router/latest/docs/routing/route-trees.md

An example of a valid file-based route tree configuration using directory and file naming conventions.

```text
/routes
â”œâ”€â”€ __root.tsx
â”œâ”€â”€ index.tsx
â”œâ”€â”€ about.tsx
â”œâ”€â”€ posts/
â”‚   â”œâ”€â”€ index.tsx
â”‚   â”œâ”€â”€ $postId.tsx
â”œâ”€â”€ posts.$postId.edit.tsx
â”œâ”€â”€ settings/
â”‚   â”œâ”€â”€ profile.tsx
â”‚   â”œâ”€â”€ notifications.tsx
â”œâ”€â”€ _pathlessLayout/
â”‚   â”œâ”€â”€ route-a.tsx
â”œâ”€â”€ â”œâ”€â”€ route-b.tsx
â”œâ”€â”€ files/
â”‚   â”œâ”€â”€ $.tsx
```

--------------------------------

### Configure Hydration Options with Custom GC Time

Source: https://tanstack.com/router/latest/docs/integrations/query.md

Example of setting a specific garbage collection time for hydrated queries during router setup.

```tsx
import { QueryClient } from '@tanstack/react-query'
import { createRouter } from '@tanstack/react-router'
import { setupRouterSsrQueryIntegration } from '@tanstack/react-router-ssr-query'
import { routeTree } from './routeTree.gen'

export function getRouter() {
  const queryClient = new QueryClient()

  const router = createRouter({
    routeTree,
    context: { queryClient },
  })

  setupRouterSsrQueryIntegration({
    router,
    queryClient,
    hydrateOptions: {
      defaultOptions: {
        queries: {
          gcTime: 5 * 60 * 1000,
        },
      },
    },
  })

  return router
}
```

--------------------------------

### Main Application Entry Point

Source: https://tanstack.com/router/latest/docs/framework/react/examples/authenticated-routes

Initializes the React application and sets up the router registration.

```typescript
'@tanstack/react-router' { interface Register { router: typeof router } } function InnerApp() { const auth = useAuth() return  } function App() { return (  ) } const rootElement = document.getElementById('app')! if (!rootElement.innerHTML) { const root = ReactDOM.createRoot(rootElement) root.render(  , ) } 
```

--------------------------------

### Configure Main Entry Point

Source: https://tanstack.com/router/latest/docs/installation/manual.md

Initializes the router instance and renders the application to the DOM.

```tsx
/* @refresh reload */
import { render } from 'solid-js/web'
import { RouterProvider, createRouter } from '@tanstack/solid-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/solid-router' {
  interface Register {
    router: typeof router
  }
}

// Render the app
const rootElement = document.getElementById('root')!

render(() => <RouterProvider router={router} />, rootElement)
```

--------------------------------

### Configure Router and Mount Application

Source: https://tanstack.com/router/latest/docs/framework/react/examples/basic

Configures the route tree, initializes the router instance, and renders the application to the DOM.

```javascript
const routeTree = rootRoute.addChildren([
  postsLayoutRoute.addChildren([postRoute, postsIndexRoute]),
  pathlessLayoutRoute.addChildren([
    nestedPathlessLayout2Route.addChildren([
      pathlessLayoutARoute,
      pathlessLayoutBRoute,
    ]),
  ]),
  indexRoute,
])

// Set up a Router instance
const router = createRouter({
  routeTree,
  defaultPreload: 'intent',
  defaultStaleTime: 5000,
  scrollRestoration: true,
})

// Register things for typesafety
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(<RouterProvider router={router} />)
}
```

--------------------------------

### Install Clerk dependency

Source: https://tanstack.com/router/latest/docs/how-to/setup-auth-providers.md

Install the required Clerk React package.

```bash
npm install @clerk/clerk-react
```

--------------------------------

### Main Entry Point Configuration

Source: https://tanstack.com/router/latest/docs/framework/react/examples/basic-devtools-panel

Initializes the React application with TanStack Router and QueryClient, including the Devtools Panel.

```typescript
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import { QueryClient, QueryClientProvider } 
from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/
react-query-devtools'
import {
Outlet,
RouterProvider,
Link,
createRouter,
createRoute,
createRootRoute,
} from '@tanstack/react-router'
import { TanStackRouterDevtoolsPanel } from 
'@tanstack/react-router-devtools'
import './styles.css'
const rootRoute = createRootRoute({
```

--------------------------------

### Initialize RootRoute and Router

Source: https://tanstack.com/router/latest/docs/api/router/RootRouteClass.md

Demonstrates creating a root route instance and building a route tree for the router.

```tsx
import { RootRoute, createRouter, Outlet } from '@tanstack/react-router'

const rootRoute = new RootRoute({
  component: () => <Outlet />,
  // ... root route options
})

const routeTree = rootRoute.addChildren([
  // ... other routes
])

const router = createRouter({
  routeTree,
})
```

--------------------------------

### Using useNavigate for programmatic navigation

Source: https://tanstack.com/router/latest/docs/api/router/useNavigateHook.md

Demonstrates initializing the navigate function with an optional 'from' path and triggering navigation with various options like search parameters, hashes, and state.

```tsx
import { useNavigate } from '@tanstack/react-router'

function PostsPage() {
  const navigate = useNavigate({ from: '/posts' })
  const handleClick = () => navigate({ search: { page: 2 } })
  // ...
}

function Component() {
  const navigate = useNavigate()
  return (
    <div>
      <button
        onClick={() =>
          navigate({
            to: '/posts',
          })
        }
      >
        Posts
      </button>
      <button
        onClick={() =>
          navigate({
            to: '/posts',
            search: { page: 2 },
          })
        }
      >
        Posts (Page 2)
      </button>
      <button
        onClick={() =>
          navigate({
            to: '/posts',
            hash: 'my-hash',
          })
        }
      >
        Posts (Hash)
      </button>
      <button
        onClick={() =>
          navigate({
            to: '/posts',
            state: { from: 'home' },
          })
        }
      >
        Posts (State)
      </button>
    </div>
  )
}
```

--------------------------------

### Initialize Router and Root Route

Source: https://tanstack.com/router/latest/docs/framework/react/examples/quickstart

Sets up the main entry point for the application using createRootRoute and createRouter.

```typescript
import React, { StrictMode } from 'react'
import ReactDOM from 'react-dom/client'
import {
Link,
Outlet,
RouterProvider,
createRootRoute,
createRoute,
createRouter,
} from '@tanstack/react-router'
import { TanStackRouterDevtools } from
'@tanstack/react-router-devtools'
import './styles.css'
const rootRoute = createRootRoute({
component: () => (
<>
<div className="p-2 flex gap-2">
<Link to="/" className="[&.active]
:font-bold">
Home
</Link>{' '}
```

--------------------------------

### Initialize Router and Render Application

Source: https://tanstack.com/router/latest/docs/framework/react/examples/basic-file-based

Configures the router instance with default settings and renders the RouterProvider to the DOM.

```typescript
import React from 'react'
import ReactDOM from 'react-dom/client'
import { RouterProvider, createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'
import './styles.css'

// Set up a Router instance
const router = createRouter({
  routeTree,
  defaultPreload: 'intent',
  defaultStaleTime: 5000,
  scrollRestoration: true,
})

// Register things for typesafety
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(<RouterProvider router={router} />)
}
```

--------------------------------

### Verify package.json dependencies

Source: https://tanstack.com/router/latest/docs/quick-start.md

Check your package.json to ensure the router dependency is correctly installed.

```json
{
  "dependencies": {
    "@tanstack/react-router": "^x.x.x"
  }
}
```

```json
{
  "dependencies": {
    "@tanstack/solid-router": "^x.x.x"
  }
}
```

--------------------------------

### Initialize Application with Providers

Source: https://tanstack.com/router/latest/docs/framework/react/examples/basic-react-query

Wrap the application with QueryClientProvider and RouterProvider to enable data fetching and routing.

```typescript
const rootElement = document.getElementById('app')!

if (!rootElement.innerHTML) {
  const root = ReactDOM.createRoot(rootElement)

  root.render(
    <QueryClientProvider client={queryClient}>
      <RouterProvider router={router} />
    </QueryClientProvider>,
  )
}
```

--------------------------------

### Basic optional parameter navigation

Source: https://tanstack.com/router/latest/docs/guide/navigation.md

Examples of navigating with, without, or inheriting optional parameters.

```tsx
// Navigate with optional parameter
<Link
  to="/posts/{-$category}"
  params={{ category: 'tech' }}
>
  Tech Posts
</Link>

// Navigate without optional parameter
<Link
  to="/posts/{-$category}"
  params={{ category: undefined }}
>
  All Posts
</Link>

// Navigate using parameter inheritance
<Link
  to="/posts/{-$category}"
  params={{}}
>
  Current Category
</Link>
```

--------------------------------

### Initialize Router in Main Entry

Source: https://tanstack.com/router/latest/docs/installation/manual.md

Configures the router instance and renders the application within the RouterProvider.

```tsx
import { StrictMode } from 'react'
import ReactDOM from 'react-dom/client'
import { RouterProvider, createRouter } 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
  }
}

// Render the app
const rootElement = document.getElementById('root')!
if (!rootElement.innerHTML) {
  const root = ReactDOM.createRoot(rootElement)
  root.render(
    <StrictMode>
      <RouterProvider router={router} />
    </StrictMode>,
  )
}
```

--------------------------------

### Define Lazy Loaded Route

Source: https://tanstack.com/router/latest/docs/framework/react/examples/kitchen-sink

Example of code-splitting a route component using lazyRouteComponent.

```typescript
const expensiveRoute = createRoute({
  getParentRoute: () => rootRoute,
  // Your elements can be asynchronous, which means you can code-split!
  path: 'expensive',
  component: lazyRouteComponent(() => import('./Expensive')),
})
```

--------------------------------

### Read URL parameters

Source: https://tanstack.com/router/latest/docs/installation/migrate-from-react-router.md

Example of using the useParams hook to access route parameters.

```typescript
const params = useParams({ from: "/orders/$orderId" })
```

--------------------------------

### Install TanStack Router

Source: https://tanstack.com/router/latest/docs/how-to/install.md

Use your preferred package manager to add the @tanstack/react-router dependency to your project.

```sh
npm install @tanstack/react-router
```

```sh
pnpm add @tanstack/react-router
```

```sh
yarn add @tanstack/react-router
```

```sh
bun add @tanstack/react-router
```

```sh
deno add npm:@tanstack/react-router
```

--------------------------------

### Configure Router and React Query in Main Entry

Source: https://tanstack.com/router/latest/docs/framework/react/examples/router-monorepo-react-query

Initializes the application by mapping route IDs to components and error handlers, then renders the app wrapped in QueryClientProvider and RouterProvider.

```typescript
import React, { StrictMode } from 'react'
import ReactDOM from 'react-dom/client'
import { RouterProvider } from '@tanstack/react-router'
import { QueryClientProvider } from '@tanstack/react-query'
import { queryClient, router } from '@router-mono-react-query/router'
import {
  PostErrorComponent,
  PostIdComponent,
  PostsListComponent,
} from '@router-mono-react-query/post-feature'
import { RootComponent } from './rootComponent'
import type { RouterIds } from '@router-mono-react-query/router'
import './style.css'

// Not lazy loaded for simplicity, but you could expose from your library component
// individually, and enforce here to use react lazy components via typings
// so that you have code splitting
const routerMap = {
  '/': PostsListComponent,
  '/$postId': PostIdComponent,
  __root__: RootComponent,
} as const satisfies Record<RouterIds, () => React.ReactElement>

Object.entries(routerMap).forEach(([path, component]) => {
  const foundRoute = router.routesById[path as RouterIds]

  foundRoute.update({
    component: component,
  })
})

// And you can do the same logic with custom error pages, and any other properties
const errorComponentMap = {
  '/': null,
  '/$postId': PostErrorComponent,
  __root__: null,
} as const satisfies Record<RouterIds, React.ComponentType<any> | null>

Object.entries(errorComponentMap).forEach(([path, component]) => {
  if (!component) {
    return
  }

  const foundRoute = router.routesById[path as RouterIds]
  foundRoute.update({
    errorComponent: component,
  })
})

// Render the app
const rootElement = document.getElementById('app')!
if (!rootElement.innerHTML) {
  const root = ReactDOM.createRoot(rootElement)
  root.render(
    <StrictMode>
      <QueryClientProvider client={queryClient}>
        <RouterProvider router={router} />
      </QueryClientProvider>
    </StrictMode>,
  )
}
```

--------------------------------

### Define a route with a path parameter

Source: https://tanstack.com/router/latest/docs/guide/path-params.md

Example of defining a route with a path parameter in React and Solid.

```tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => {
    return fetchPost(params.postId)
  },
})
```

```tsx
import { createFileRoute } from '@tanstack/solid-router'

export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => {
    return fetchPost(params.postId)
  },
})
```

--------------------------------

### Initialize a Router with createRouter

Source: https://tanstack.com/router/latest/docs/api/router/createRouterFunction.md

Configures a new router instance with a route tree and default preload settings, then provides it to the application via RouterProvider.

```tsx
import { createRouter, RouterProvider } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

const router = createRouter({
  routeTree,
  defaultPreload: 'intent',
})

export default function App() {
  return <RouterProvider router={router} />
}
```

--------------------------------

### Replace Link component props

Source: https://tanstack.com/router/latest/docs/installation/migrate-from-react-router.md

Example of updating the Link component to use the to and params props.

```jsx
params={{ orderId: order.id }}
```

--------------------------------

### Usage of ValidateLinkOptionsArray

Source: https://tanstack.com/router/latest/docs/guide/type-utilities.md

Example of providing navigation options relative to a specific path using ValidateLinkOptionsArray.

```tsx
<Menu
  from="/posts"
  items={[{ to: '.' }, { to: './$postId', params: { postId: 'postId' } }]}
/>
```

--------------------------------

### createRouter(options)

Source: https://tanstack.com/router/latest/docs/api/router/createRouterFunction.md

Initializes a new Router instance with the provided configuration options.

```APIDOC
## createRouter(options)

### Description
The `createRouter` function is used to create a new `Router` instance. It requires a `RouterOptions` object to configure the router's behavior, such as the route tree and default preload settings.

### Parameters
- **options** (RouterOptions) - Required - The configuration object used to initialize the router.

### Returns
- **Router** - An instance of the router that can be passed to a `RouterProvider`.

### Example
```tsx
import { createRouter, RouterProvider } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

const router = createRouter({
  routeTree,
  defaultPreload: 'intent',
})

export default function App() {
  return <RouterProvider router={router} />
}
```
```

--------------------------------

### Usage of type-safe Menu items

Source: https://tanstack.com/router/latest/docs/guide/type-utilities.md

Example of passing validated link options to the Menu component.

```tsx
<Menu
  items={[
    { to: '/posts' },
    { to: '/posts/$postId', params: { postId: 'postId' } },
  ]}
/>
```

--------------------------------

### Define default search object

Source: https://tanstack.com/router/latest/docs/guide/custom-search-param-serialization.md

Example of a search object structure used for default serialization.

```tsx
const search = {
  page: 1,
  sort: 'asc',
  filters: { author: 'tanner', min_words: 800 },
}
```

--------------------------------

### Initialize Router Instance

Source: https://tanstack.com/router/latest/docs/guide/creating-a-router.md

Create a new router instance using the framework-specific package.

```tsx
import { createRouter } from '@tanstack/react-router'

const router = createRouter({
  // ...
})
```

```tsx
import { createRouter } from '@tanstack/solid-router'

const router = createRouter({
  // ...
})
```

--------------------------------

### Initialize Paraglide

Source: https://tanstack.com/router/latest/docs/guide/internationalization-i18n.md

Run this command to initialize the Paraglide-js library in your project.

```bash
npx @inlang/paraglide-js@latest init
```

--------------------------------

### Non-Nested Route Structure

Source: https://tanstack.com/router/latest/docs/routing/routing-concepts.md

Example of a flat route tree using the underscore suffix to un-nest a route.

```text
routes/
â”œâ”€â”€ posts.tsx
â”œâ”€â”€ posts.$postId.tsx
â”œâ”€â”€ posts_.$postId.edit.tsx
```

--------------------------------

### Configure Router and Route Tree

Source: https://tanstack.com/router/latest/docs/framework/react/examples/kitchen-sink-react-query

Assembles the route tree and initializes the router with React Query context and default preload settings.

```typescript
const routeTree = rootRoute.addChildren([
  indexRoute,
  dashboardLayoutRoute.addChildren([
    dashboardIndexRoute,
    invoicesLayoutRoute.addChildren([invoicesIndexRoute, invoiceRoute]),
    usersLayoutRoute.addChildren([usersIndexRoute, userRoute]),
  ]),
  expensiveRoute,
  authPathlessLayoutRoute.addChildren([profileRoute]),
  loginRoute,
  pathlessLayoutRoute.addChildren([pathlessLayoutARoute, pathlessLayoutBRoute]),
])

const queryClient = new QueryClient()

const router = createRouter({
  routeTree,
  defaultPendingComponent: () => (
    <div className={`p-2 text-2xl`}>
      <Spinner />
    </div>
  ),
  defaultErrorComponent: ({ error }) => <ErrorComponent error={error} />,
  context: {
    auth: undefined!, // We'll inject this when we render
    queryClient,
  },
  defaultPreload: 'intent',
  // Since we're using React Query, we don't want loader calls to ever be stale
  // This will ensure that the loader is always called when the route is preloaded or visited
  defaultPreloadStaleTime: 0,
  scrollRestoration: true,
})

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}
```

--------------------------------

### Define a lazy file route

Source: https://tanstack.com/router/latest/docs/api/router/createLazyFileRouteFunction.md

Example of using createLazyFileRoute to define a route component that is lazily loaded.

```tsx
import { createLazyFileRoute } from '@tanstack/react-router'

export const Route = createLazyFileRoute('/')({
  component: IndexComponent,
})

function IndexComponent() {
  const data = Route.useLoaderData()
  return <div>{data}</div>
}
```

--------------------------------

### Create routes directory

Source: https://tanstack.com/router/latest/docs/installation/migrate-from-react-location.md

Initialize the directory structure for file-based routing.

```sh
mkdir src/routes
```

--------------------------------

### Implement Solid SSR entry-server

Source: https://tanstack.com/router/latest/docs/guide/ssr.md

Configures the server-side entry point for Solid using createRequestHandler and the default render handler.

```tsx
import {
  createRequestHandler,
  defaultRenderHandler,
} from '@tanstack/solid-router/ssr/server'
import { createRouter } from './router'

export async function render({ request }: { request: Request }) {
  const handler = createRequestHandler({ request, createRouter })

  return await handler(defaultRenderHandler)
}
```

--------------------------------

### Configure Router Instance

Source: https://tanstack.com/router/latest/docs/how-to/setup-authentication.md

Initializes the router with a placeholder context and registers the router type.

```tsx
import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

export const router = createRouter({
  routeTree,
  context: {
    // auth will be passed down from App component
    auth: undefined!,
  },
})

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}
```

--------------------------------

### Hydrate Solid Application

Source: https://tanstack.com/router/latest/docs/guide/ssr.md

Use this setup to hydrate a Solid application on the client side after server-side rendering.

```tsx
import { hydrate } from 'solid-js/web'
import { RouterClient } from '@tanstack/solid-router/ssr/client'
import { createRouter } from './router'

const router = createRouter()

hydrate(() => <RouterClient router={router} />, document.body)
```

--------------------------------

### Hydrate React Application

Source: https://tanstack.com/router/latest/docs/guide/ssr.md

Use this setup to hydrate a React application on the client side after server-side rendering.

```tsx
import { hydrateRoot } from 'react-dom/client'
import { RouterClient } from '@tanstack/react-router/ssr/client'
import { createRouter } from './router'

const router = createRouter()

hydrateRoot(document, <RouterClient router={router} />)
```

--------------------------------

### Scaffold a new project with TanStack CLI

Source: https://tanstack.com/router/latest/docs/quick-start.md

Use the CLI to generate a new project with router-only configuration for React or Solid.

```bash
@tanstack/cli create --router-only
```

```bash
@tanstack/cli create --router-only --framework solid
```

--------------------------------

### Import Solid Router Devtools in Production

Source: https://tanstack.com/router/latest/docs/devtools.md

Import TanStackRouterDevtoolsInProd for use in production environments to ensure devtools are available.

```tsx
import { TanStackRouterDevtoolsInProd } from '@tanstack/solid-router-devtools'
```

--------------------------------

### Type-Safe Link Navigation

Source: https://tanstack.com/router/latest/docs/guide/navigation.md

Example of using a route object's 'to' property to create a type-safe link.

```tsx
import { Route as aboutRoute } from './routes/about.tsx'

function Comp() {
  return <Link to={aboutRoute.to}>About</Link>
}
```

--------------------------------

### Define Index Route Component

Source: https://tanstack.com/router/latest/docs/framework/react/examples/authenticated-routes

A basic index route component demonstrating navigation options for the authenticated-routes example.

```typescript
import { createFileRoute } from '@tanstack/react-router' import { Link } from '@tanstack/react-router' export const Route = createFileRoute('/')({ component: HomeComponent, }) function HomeComponent() { return ( 
# Welcome!
**IMPORTANT!!!** This is just an example of how to use authenticated routes with TanStack Router.   
This is NOT an example how you'd write a production-level authentication system.   
You'll need to take the concepts and patterns used in this example and adapt then to work with your authentication flow/system for your app. 
You are currently on the index route of the{' '} **authenticated-routes** example. 
You can try going through these options.
  1. Go to the public login page. 
  2. Go to the auth-only dashboard page. 
  3. Go to the auth-only invoices page. 


) } 
```

--------------------------------

### Configure Router with React Query

Source: https://tanstack.com/router/latest/docs/framework/react/examples/kitchen-sink-react-query-file-based

Initializes the QueryClient and creates the router instance with custom pending and error components, context injection, and preload settings.

```typescript
import * as React from 'react'
import ReactDOM from 'react-dom/client'
import {
  ErrorComponent,
  RouterProvider,
  createRouter,
} from '@tanstack/react-router'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { auth } from './utils/auth'
import { Spinner } from './components/Spinner'
import { routeTree } from './routeTree.gen'
import { useSessionStorage } from './hooks/useSessionStorage'
import './styles.css'

//

export const queryClient = new QueryClient()

const router = createRouter({
  routeTree,
  defaultPendingComponent: () => (
    <div className={`p-2 text-2xl`}>
      <Spinner />
    </div>
  ),
  defaultErrorComponent: ({ error }) => <ErrorComponent error={error} />,
  context: {
    auth: undefined!, // We'll inject this when we render
    queryClient,
  },
  defaultPreload: 'intent',
  // Since we're using React Query, we don't want loader calls to ever be stale
  // This will ensure that the loader is always called when the route is preloaded or visited
  defaultPreloadStaleTime: 0,
  scrollRestoration: true,
})

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

function App() {
  // This stuff is just to tweak our sandbox setup in real-time
  const [loaderDelay, setLoaderDelay] = useSessionStorage('loaderDelay', 500)
  const [pendingMs, setPendingMs] = useSessionStorage('pendingMs', 1000)
  const [pendingMinMs, setPendingMinMs] = useSessionStorage('pendingMinMs', 500)

  return (
    <>
      <div className="text-xs fixed w-52 shadow-md shadow-black/20 rounded-sm bottom-2 left-2 bg-white dark:bg-gray-800 bg-opacity-75 border-b flex flex-col gap-1 flex-wrap items-left divide-y">
        <div className="p-2 space-y-2">
          <div className="flex gap-2">
            <button
              className="bg-blue-500 text-white rounded-sm p-1 px-2"
              onClick={() => {
                setLoaderDelay(150)
              }}
            >
              Fast
            </button>
            <button
              className="bg-blue-500 text-white rounded-sm p-1 px-2"
              onClick={() => {
                setLoaderDelay(500)
              }}
            >
              Fast 3G
            </button>
            <button
              className="bg-blue-500 text-white rounded-sm p-1 px-2"
              onClick={() => {
                setLoaderDelay(2000)
              }}
            >
              Slow 3G
            </button>
          </div>
          <div>
            <div>Loader Delay: {loaderDelay}ms</div>
            <input
              type="range"
              min="0"
              max="5000"
              step="100"
              value={loaderDelay}
              onChange={(e) => setLoaderDelay(e.target.valueAsNumber)}
              className="w-full"
            />
          </div>
        </div>
        <div className="p-2 space-y-2">
          <div className="flex gap-2">
            <button
              className="bg-blue-500 text-white rounded-sm p-1 px-2"
              onClick={() => {
                setPendingMs(1000)
                setPendingMinMs(500)
              }}
            >
              Reset to Default
            </button>
          </div>
          <div>
            <div>defaultPendingMs: {pendingMs}ms</div>
            <input
              type="range"
              min="0"
              max="5000"
              step="100"
              value={pendingMs}
              onChange={(e) => setPendingMs(e.target.valueAsNumber)}
              className="w-full"
            />
          </div>
          <div>
            <div>defaultPendingMinMs: {pendingMinMs}ms</div>
            <input
              type="range"
              min="0"
              max="5000"
              step="100"
              value={pendingMinMs}
              onChange={(e) => setPendingMinMs(e.target.valueAsNumber)}
              className="w-full"
            />
          </div>
        </div>
      </div>
      <RouterProvider
        router={router}
        defaultPreload="intent"
        defaultPendingMs={pendingMs}
        defaultPendingMinMs={pendingMinMs}
        context={{
          auth,
        }}
      />
    </>
  )
}

const rootElement = document.getElementById('app')!
if (!rootElement.innerHTML) {
  const root = ReactDOM.createRoot(rootElement)
  root.render(
    // <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>,
    // </React.StrictMode>
  )
}
```

--------------------------------

### Read search parameters

Source: https://tanstack.com/router/latest/docs/installation/migrate-from-react-router.md

Example of using the useSearch hook to read search parameters from a specific route path.

```typescript
const { page } = useSearch({ from: productPage.fullPath })
```

--------------------------------

### Initialize Router with Context

Source: https://tanstack.com/router/latest/docs/guide/router-context.md

Provide the initial context values when creating the router instance.

```tsx
import { createRouter } from '@tanstack/react-router'

import { routeTree } from './routeTree.gen'

const router = createRouter({
  routeTree,
  context: {
    foo: true,
  },
})
```

```tsx
import { createRouter } from '@tanstack/solid-router'

import { routeTree } from './routeTree.gen'

const router = createRouter({
  routeTree,
  context: {
    foo: true,
  },
})
```

--------------------------------

### Implement PermissionGuard in components

Source: https://tanstack.com/router/latest/docs/how-to/setup-rbac.md

Usage examples for protecting UI elements with specific roles, permissions, or combined requirements.

```tsx
import { PermissionGuard } from '../components/PermissionGuard'

function SomeComponent() {
  return (
    <div>
      <h1>Dashboard</h1>

      <PermissionGuard roles={['admin']}>
        <button className="bg-red-600 text-white px-4 py-2 rounded">
          Admin Only Button
        </button>
      </PermissionGuard>

      <PermissionGuard
        permissions={['users:write']}
        fallback={<p className="text-gray-500">You cannot edit users</p>}
      >
        <button className="bg-blue-600 text-white px-4 py-2 rounded">
          Edit Users
        </button>
      </PermissionGuard>

      <PermissionGuard
        roles={['admin', 'moderator']}
        permissions={['content:moderate']}
        requireAll={true}
      >
        <button className="bg-yellow-600 text-white px-4 py-2 rounded">
          Moderate Content (Admin/Mod + Permission)
        </button>
      </PermissionGuard>
    </div>
  )
}
```
Tokens:
Raw