File Route

File Route API

File-based routing APIs for creating routes from the filesystem.

createFileRoute

Creates a file-based Route factory for a given path.

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

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

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

Parameters

path · string · required

File path literal for the route (usually auto-generated by the tsr generator).

Returns

createRoute · Function

A function that accepts Route options and returns a Route instance.

The returned function accepts all the same options as createRoute, including:

• loader - Load data for the route
• beforeLoad - Run before the route loads
• component - The component to render
• errorComponent - Error boundary component
• pendingComponent - Loading component
• notFoundComponent - Not found component
• validateSearch - Validate search params
• loaderDeps - Loader dependencies
• staleTime - Cache staleness time
• gcTime - Garbage collection time
• And more…

File Route Structure

When using file-based routing, your route files follow a specific naming convention:

Standard Routes

routes/
  index.tsx              → /
  about.tsx              → /about
  posts/
    index.tsx            → /posts
    $postId.tsx          → /posts/$postId
    $postId/
      edit.tsx           → /posts/$postId/edit

Layout Routes

Layout routes don’t add a path segment but wrap child routes:

routes/
  _layout.tsx            → wraps children without path
  _layout/
    dashboard.tsx        → /dashboard
    settings.tsx         → /settings

Route Groups

Route groups organize routes without affecting the URL:

routes/
  (auth)/                → no path segment
    login.tsx            → /login
    register.tsx         → /register

createLazyFileRoute

Creates a lazily-configurable file-based route stub by file path for code-splitting.

// routes/posts.$postId.lazy.tsx
import { createLazyFileRoute } from '@tanstack/react-router'

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

function PostComponent() {
  const { postId } = Route.useParams()
  return <div>Post {postId}</div>
}

Parameters

id · string · required

File path literal for the route file.

Returns

createLazyRoute · Function

A function that accepts lazy route options and returns a LazyRoute.

Lazy route options include only non-critical route options:

• component - The component to render
• pendingComponent - Loading component
• errorComponent - Error boundary component
• notFoundComponent - Not found component

Code Splitting Pattern

Split your routes into two files for optimal bundle size:

Main Route File

// routes/posts.$postId.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => {
    // Critical data loading
    const post = await fetchPost(params.postId)
    return { post }
  },
  // No component here - it's in the lazy file
})

Lazy File

// 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 <h1>{post.title}</h1>
}

Route File Exports

Route files created with createFileRoute can export the following:

Route Export

export const Route = createFileRoute('/posts')({
  // Route options
})

Route · Route · required

The route instance created by createFileRoute. This must be the default export or named Route.

Path Parameters

Define path parameters in your file names:

Single Parameter

routes/posts.$postId.tsx → /posts/:postId

Multiple Parameters

routes/posts.$postId.comments.$commentId.tsx → /posts/:postId/comments/:commentId

Splat/Catch-all

routes/files.$.tsx → /files/*

Search Parameter Validation

Validate and type search parameters:

import { createFileRoute } from '@tanstack/react-router'
import { z } from 'zod'
import { zodValidator } from '@tanstack/zod-adapter'

const searchSchema = z.object({
  page: z.number().default(1),
  filter: z.enum(['all', 'active', 'completed']).default('all'),
})

export const Route = createFileRoute('/posts')({
  validateSearch: zodValidator(searchSchema),
  loaderDeps: ({ search }) => ({ page: search.page }),
  loader: async ({ deps }) => {
    const posts = await fetchPosts(deps.page)
    return { posts }
  },
})

Route Context

Add context to a route and its children:

export const Route = createFileRoute('/posts/$postId')({
  beforeLoad: async ({ params, context }) => {
    const post = await fetchPost(params.postId)
    return {
      post,
      getComments: () => fetchComments(params.postId),
    }
  },
})

Child routes can access this context:

// routes/posts.$postId.comments.tsx
export const Route = createFileRoute('/posts/$postId/comments')({
  loader: async ({ context }) => {
    const comments = await context.getComments()
    return { comments }
  },
})