File-based routing

Set up automatic route generation from your file system structure

File-based routing automatically generates your route tree from your file system structure, eliminating the need to manually define routes in code.

Overview

With file-based routing, you create route files in a designated directory (typically src/routes/), and TanStack Router automatically generates the route configuration for you. This provides:

• Zero configuration - Routes are automatically discovered
• Type safety - Full TypeScript support with generated types
• Code splitting - Automatic code splitting per route
• Colocation - Keep route logic close to the route definition

Setup

1. Install the plugin

   Install the Vite plugin (or your bundler’s equivalent):

   npm

   npm install -D @tanstack/router-plugin
   
2. Configure the plugin

   Add the plugin to your Vite config:

   vite.config.ts

   import { defineConfig } from 'vite'
   import react from '@vitejs/plugin-react'
   import { TanStackRouterVite } from '@tanstack/router-plugin/vite'
   
   export default defineConfig({
     plugins: [TanStackRouterVite(), react()],
   })
   
3. Create your route files

   Create route files in src/routes/ using the createFileRoute function:

   src/routes/__root.tsx

   import { createRootRoute, Outlet } from '@tanstack/react-router'
   import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
   
   export const Route = createRootRoute({
     component: () => (
       <>
         <Outlet />
         <TanStackRouterDevtools />
       </>
     ),
   })
   

   src/routes/index.tsx

   import { createFileRoute } from '@tanstack/react-router'
   
   export const Route = createFileRoute('/')({
     component: () => <div>Welcome Home!</div>,
   })
   

File naming conventions

Standard routes

src/routes/
  __root.tsx       -> /
  index.tsx        -> /
  about.tsx        -> /about
  posts.tsx        -> /posts
  posts/index.tsx  -> /posts
  posts/$id.tsx    -> /posts/:id

Dynamic parameters

Use $ prefix for path parameters:

posts/$postId.tsx           -> /posts/:postId
users/$userId/edit.tsx      -> /users/:userId/edit

Pathless routes

Use _ prefix for layout routes without adding to the path:

_layout.tsx                 -> Wraps children but doesn't add to URL
_layout/dashboard.tsx       -> /dashboard (with _layout wrapper)

Route groups

Use parentheses for organizational grouping:

(auth)/login.tsx            -> /login
(auth)/register.tsx         -> /register

Route options

Define route behavior using the route object:

src/routes/posts/$postId.tsx

import { createFileRoute } from '@tanstack/react-router'
import { fetchPost } from '@/api'

export const Route = createFileRoute('/posts/$postId')({
  // Load data before rendering
  loader: async ({ params }) => {
    return await fetchPost(params.postId)
  },
  // Main component
  component: PostComponent,
  // Error boundary
  errorComponent: ({ error }) => <div>Error: {error.message}</div>,
  // Pending component
  pendingComponent: () => <div>Loading post...</div>,
})

function PostComponent() {
  const { postId } = Route.useParams()
  const post = Route.useLoaderData()
  
  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </article>
  )
}

Code splitting

Separate route code from component code for better performance:

src/routes/posts/$postId.tsx

import { createFileRoute } from '@tanstack/react-router'
import { fetchPost } from '@/api'

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

src/routes/posts/$postId.lazy.tsx

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

export const Route = createLazyFileRoute('/posts/$postId')({
  component: PostComponent,
})

function PostComponent() {
  const post = Route.useLoaderData()
  return <article>{post.title}</article>
}

Type generation

The plugin automatically generates type-safe route definitions:

src/routeTree.gen.ts

// This file is auto-generated by TanStack Router
import type { RootRoute } from './routes/__root'
import type { IndexRoute } from './routes/index'

export interface FileRouteTypes {
  '/': {
    component: typeof IndexRoute
  }
}

Commit the generated routeTree.gen.ts file to version control to enable type checking in CI/CD.

Best practices

Keep route files focused

Route files should contain route configuration and data loading logic. Move complex components to separate files.

Use lazy loading for large components

Split heavy components into .lazy.tsx files to reduce initial bundle size.

Leverage type safety

Use Route.useParams(), Route.useSearch(), and Route.useLoaderData() for fully typed data access.

Next steps

Data loading

Learn how to load data for your routes

Path params

Master dynamic route parameters