Using Tanstack Router

Quick Reference

Core Patterns

File-Based Routing

src/routes/
├── __root.tsx           # Root layout (required)
├── index.tsx            # / route
├── assets/
│   ├── index.tsx        # /assets
│   └── $assetId.tsx     # /assets/:assetId (dynamic param)
└── settings/
    ├── _layout.tsx      # Pathless layout
    ├── index.tsx        # /settings
    └── profile.tsx      # /settings/profile

For complete file naming conventions, see file-conventions.md.

Route Definition

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

export const Route = createFileRoute('/assets')({
  component: AssetList,
})

function AssetList() {
  return <div>Asset List</div>
}

Route Loaders

export const Route = createFileRoute('/assets/$assetId')({
  loader: async ({ params }) => {
    const asset = await fetchAsset(params.assetId)
    return { asset }
  },
  component: AssetDetails,
})

function AssetDetails() {
  const { asset } = Route.useLoaderData()
  return <div>{asset.name}</div>
}

For loader patterns (beforeLoad vs loader, loaderDeps, parallel loading), see loader-patterns.md.

Search Params with Zod

import { zodValidator, fallback } from '@tanstack/zod-adapter'
import { z } from 'zod'

const searchSchema = z.object({
  status: z.enum(['active', 'inactive']).optional(),
  page: fallback(z.number().int().positive(), 1),
  search: z.string().default(''),
})

export const Route = createFileRoute('/assets')({
  validateSearch: zodValidator(searchSchema),
})

function AssetList() {
  const { status, page, search } = Route.useSearch()
  return <div>Page {page}</div>
}

For detailed validation patterns, see search-validation.md.

Type-Safe Navigation

import { useNavigate, Link } from '@tanstack/react-router'

function AssetCard({ asset }: { asset: Asset }) {
  const navigate = useNavigate()

  return (
    <Link
      to="/assets/$assetId"
      params={{ assetId: asset.id }}
      search={{ tab: 'risks' }}
    >
      {asset.name}
    </Link>
  )
}

For navigation patterns, see router-navigation-patterns.md.

Authentication Guards

import { createFileRoute, redirect } from "@tanstack/react-router";

export const Route = createFileRoute("/settings")({
  beforeLoad: async ({ context }) => {
    if (!context.auth.isAuthenticated) {
      throw redirect({ to: "/login", search: { redirect: "/settings" } });
    }
  },
});

Code Splitting

// assets.tsx - Critical options
export const Route = createFileRoute("/assets")({
  loader: async () => fetchAssets(),
});

// assets.lazy.tsx - Non-critical options
import { createLazyFileRoute } from "@tanstack/react-router";

export const Route = createLazyFileRoute("/assets")({
  component: AssetList,
  pendingComponent: LoadingSpinner,
});

For code splitting patterns, see code-splitting.md.

TanStack Query Integration

import { queryOptions } from "@tanstack/react-query";

const assetQueryOptions = (id: string) =>
  queryOptions({
    queryKey: ["assets", id],
    queryFn: () => fetchAsset(id),
  });

export const Route = createFileRoute("/assets/$assetId")({
  loader: async ({ params, context }) => {
    await context.queryClient.ensureQueryData(assetQueryOptions(params.assetId));
  },
});

For Query integration patterns, see integration-patterns.md.

Reference Navigation

Data Loading

• loader-patterns.md - beforeLoad vs loader, loaderDeps, context flow, parallel loading
• router-route-loaders.md - Legacy loader documentation

Error Handling

• error-handling.md - notFoundComponent, errorComponent, pendingComponent, notFound()

Routing & Navigation

• file-conventions.md - Complete file naming reference ($param, _layout, (groups))
• router-routing-guide.md - Comprehensive routing guide
• router-navigation-patterns.md - Navigation strategies

Advanced Patterns

• code-splitting.md - Lazy loading with .lazy.tsx, bundle optimization
• search-validation.md - Search param validation with Zod adapter
• integration-patterns.md - TanStack Query + Router integration

Anti-Patterns

❌ Don't use string routes:

navigate("/assets/" + assetId); // No type safety

✅ Use type-safe params:

navigate({ to: "/assets/$assetId", params: { assetId } });

❌ Don't fetch in components:

const { data } = useQuery(["assets", assetId], fetchAsset); // Loading flicker

✅ Fetch in loaders: