TanStack Router Patterns

TanStack Router Patterns

This skill enforces TanStack Router best practices for file-based routing in React SPA applications.

Route File Naming Conventions

Pattern	Example	URL Path	Purpose
__root.tsx	routes/__root.tsx	-	Root layout, wraps all routes
index.tsx	routes/index.tsx	/	Index route
about.tsx	routes/about.tsx	/about	Static segment
posts.tsx	routes/posts.tsx	/posts	Layout route (has <Outlet />)
posts.index.tsx	routes/posts.index.tsx	/posts	Posts index (nested in layout)
posts.$postId.tsx	routes/posts.$postId.tsx	/posts/:postId	Dynamic parameter
posts_.$postId.edit.tsx	routes/posts_.$postId.edit.tsx	/posts/:postId/edit	Pathless parent layout
_auth.tsx	routes/_auth.tsx	-	Pathless layout (no URL segment)
_auth.login.tsx	routes/_auth.login.tsx	/login	Child of pathless layout
(marketing)/	routes/(marketing)/about.tsx	/about	Route group (organization only)
$.tsx	routes/$.tsx	/*	Catch-all/splat route

Route File Structure

Basic Route

// routes/about.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/about')({
  component: AboutPage,
})

function AboutPage() {
  return <div>About Page</div>
}

Route with Loader

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

export const Route = createFileRoute('/posts/$postId')({
  loader: ({ context: { queryClient }, params }) =>
    queryClient.ensureQueryData(postQueryOptions(params.postId)),
  component: PostDetailPage,
})

function PostDetailPage() {
  const { postId } = Route.useParams()
  const post = Route.useLoaderData()

  return <PostDetail post={post} />
}

Route with Search Params

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

const postsSearchSchema = z.object({
  page: z.number().default(1),
  sort: z.enum(['newest', 'oldest', 'popular']).default('newest'),
  search: z.string().optional(),
})

export const Route = createFileRoute('/posts')({
  validateSearch: postsSearchSchema,
  component: PostsPage,
})

function PostsPage() {
  const { page, sort, search } = Route.useSearch()
  const navigate = Route.useNavigate()

  const setPage = (newPage: number) => {
    navigate({ search: (prev) => ({ ...prev, page: newPage }) })
  }

  return <PostList page={page} sort={sort} search={search} onPageChange={setPage} />
}