tanstack-router

Overview

TanStack Router is a fully type-safe router for React (and Solid) applications. It provides file-based routing, first-class search parameter management, built-in data loading, code splitting, and deep TypeScript integration. It serves as the routing foundation for TanStack Start (the full-stack framework).

Package: @tanstack/react-router CLI: @tanstack/router-cli or @tanstack/router-plugin (Vite/Rspack/Webpack) Devtools: @tanstack/react-router-devtools

Installation

npm install @tanstack/react-router
# For file-based routing with Vite:
npm install -D @tanstack/router-plugin
# Or standalone CLI:
npm install -D @tanstack/router-cli

Core Concepts

Route Trees

Routes are organized in a tree structure. The root route is the top-level layout, and child routes nest underneath.

import { createRootRoute, createRoute, createRouter } from '@tanstack/react-router'

const rootRoute = createRootRoute({
  component: RootLayout,
})

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

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

const routeTree = rootRoute.addChildren([indexRoute, aboutRoute])
const router = createRouter({ routeTree })

File-Based Routing

File-based routing automatically generates the route tree from your file structure. Configure with Vite plugin:

// vite.config.ts
import { defineConfig } from 'vite'
import { TanStackRouterVite } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [
    TanStackRouterVite(),
    // ... other plugins
  ],
})

File Naming Conventions

File Pattern	Route Type	Example Path
__root.tsx	Root layout	N/A (wraps all)
index.tsx	Index route	/
about.tsx	Static route	/about
$postId.tsx	Dynamic param	/posts/$postId
posts.tsx	Layout route	/posts/* (layout)
posts/index.tsx	Nested index	/posts
posts/$postId.tsx	Nested dynamic	/posts/123
posts_.$postId.tsx	Pathless layout	/posts/123 (different layout)
_layout.tsx	Pathless layout	N/A (groups routes)
_layout/dashboard.tsx	Grouped route	/dashboard
$.tsx	Splat/catch-all	/*
posts.$postId.edit.tsx	Dot notation	/posts/123/edit