Конструкторы маршрутов

createRootRoute(options) — единственный корневой узел; задает глобальный layout, errorBoundary, pendingBoundary и context. В v1 принято держать rootRoute в отдельном файле (__root.tsx), чтобы избежать циклических зависимостей.
createRoute(options) — базовый дочерний узел с обязательным getParentRoute.
createLazyRoute(options) — ленивый аналог; позволяет вернуть Component, loader, pendingComponent из dynamic import, сокращая initial bundle.
createFileRoute(path) / createLazyFileRoute(path) — синтаксический сахар для file-based подхода. Автоматически проставляют id вида /dashboard/reports.

Лайфхаки объявления маршрутов

Давайте layout-узлам явный id ('dashboard-layout'), чтобы потом к ним легко привязывать guards/children.
Группируйте маршруты по feature-папкам. Например, routes/dashboard/index.ts экспортирует dashboardRoute и dashboardChildren, а корневой routeTree собирается в routes/__root.tsx.
Для тестов полезно экспортировать routeTree отдельно от router, чтобы подменять context во время unit-тестирования.

Основные опции route

| Опция | Назначение | | — | — | | path | Статический ('settings') или динамический ('$userId') сегмент. Разрешены вложенные сегменты ('$orgId/projects'). | | id | Пользовательский идентификатор, обязателен, если нет path. Удобен для layout-узлов. | | component / pendingComponent / errorComponent | Компоненты для состояний. Можно задавать функцией или ссылкой на компонент. | | loader | Загрузка данных; поддерживает Promise, defer, работу с Query Client. | | beforeLoad | Выполняется до монтирования; подходит для guard-логики и вычисления context. | | shouldReload | Управляет повторными вызовами loader-а; можно возвращать false, если данные кешируются Query Client. | | meta | Свободная полезная нагрузка (title, breadcrumbs, featureFlags). | | validateSearch / parseParams | Типобезопасная валидация search/params через zod/valibot. | | pendingMs | Таймаут до показа pendingComponent; снижает “мигание” спиннера. | | wrapInSuspense | Принудительно оборачивает вложенные компоненты в Suspense (полезно при createLazyRoute). |

Работа с path/id

Динамические сегменты начинаются с $: '$userId/settings'. Для optional сегментов используйте '$userId?'.
Если нужно несколько route с одинаковым path, различайте их id и mask, но старайтесь избегать, чтобы не усложнять devtools.
При file-based подходе createFileRoute('/dashboard/$orgId') автоматически ставит path: '$orgId' и id: '/dashboard/$orgId'.

Пример layout-дерева

// routes/dashboard.tsx
export const Route = createRoute({
  getParentRoute: () => rootRoute,
  id: 'dashboard',
  component: () => (
    <DashboardShell>
      <Outlet />
    </DashboardShell>
  ),
  meta: () => ({ title: 'Панель' }),
  beforeLoad: ({ context }) => {
    if (!context.auth.user) {
      throw redirect({ to: '/login', mask: { to: '/' } })
    }
  },
})

// routes/dashboard.analytics.tsx
export const Route = createRoute({
  getParentRoute: () => dashboardRoute,
  path: 'analytics',
  component: AnalyticsPage,
  loader: async ({ context, search }) =>
    context.api.analytics.get({ range: search.range ?? '7d' }),
  validateSearch: z.object({
    range: z.enum(['7d', '30d']).default('7d'),
  }),
})

Error & pending boundary на уровне layout

createRoute({
  getParentRoute: () => dashboardRoute,
  path: 'reports',
  pendingMs: 150,
  pendingComponent: () => <Spinner />,
  errorComponent: ({ error }) => <ErrorPanel error={error} />,
  loader: async ({ context }) => context.api.reports.list(),
  component: ReportsPage,
})

Смешанный пример с ленивыми файлами

// routes/dashboard.reports.lazy.tsx
export const Route = createLazyRoute({
  component: async () => {
    const { ReportsLayout } = await import('./ReportsLayout')
    return { Component: ReportsLayout }
  },
  pendingComponent: () => <SkeletonReports />,
})

// routes/dashboard.reports.$reportId.tsx
export const Route = createFileRoute('/dashboard/reports/$reportId')({
  loader: async ({ params, context }) =>
    context.queryClient.ensureQueryData(reportQuery(params.reportId)),
  component: ReportDetails,
})

Работа с `context`

context передается из createRouter({ context }) и доступен во всех loader/beforeLoad.

const router = createRouter({
  routeTree,
  context: {
    auth: authClient,
    queryClient,
    featureFlags,
  },
})

Практические советы по context

Храните там долгоживущие сервисы (auth, QueryClient, trpcClient), а не UI-состояния.
Для SSR можно прокидывать request, но на клиенте заменяйте его сериализуемой версией (например, requestHeaders).
Layout-компоненты могут расширять context через Route.context. Например, dashboardRoute может запровайдить org всем дочерним матчам.

Реиспользование настроек через route factories

const authRouteFactory = rootRoute.createRoute({
  beforeLoad: ({ context }) => {
    if (!context.auth.user) throw redirect({ to: '/login' })
  },
})

export const settingsRoute = authRouteFactory.createRoute({
  path: 'settings',
  component: SettingsPage,
})

Фабрики + динамические параметры

const orgRouteFactory = authRouteFactory.createRoute({
  parseParams: (params) => ({
    orgId: z.string().uuid().parse(params.orgId),
  }),
})

export const orgMembersRoute = orgRouteFactory.createRoute({
  path: '$orgId/members',
  loader: ({ params, context }) =>
    context.api.org(params.orgId).members(),
})

Типы компонентов

component получает RouteComponentProps<TFullRoute>; используйте Route.useLoaderData() и Route.useSearch() для типобезопасности.
Для lazy подключений удобно писать const Route = createLazyFileRoute('/path')({ component: lazy(...) }).
Form Actions в v1 делаются через router.navigate/router.invalidate после fetch. Можно совмещать с RouterViewTransition для плавных обновлений.

Компонентные паттерны

Доставайте локальные данные через Route.useRouteContext() вместо React context, чтобы гарантировать подписку только на нужный матч.
Если layout должен отдавать данные детям, возвращайте их из component через RouteContext.Provider или Route.context.
Для избегания лишних ререндеров пользуйтесь useMatch({ select: (match) => match.loaderData.part }).

Контроль перерендеров

Оборачивайте layout-компоненты в memo, если внутри много состояния.
Используйте useRouterState({ select }), чтобы подписываться на нужные поля (например, status, location).
Включайте routerOptions.dehydrate/hydrate только при SSR; иначе React будет тратить время на сериализацию.
Loader-ы, которые возвращают большие объекты, стоит синхронизировать с Query Client (loader просто await queryClient.ensureQueryData(...)).

Lazy-маршруты и prefetch

createLazyRoute хорошо сочетается с router.loadRoute(to). Вызывайте его в onMouseEnter, чтобы подгружать bundle заранее.
usePrefetchRoute (v1.0+) позволяет подгрузить loader/компонент при пересечении sentinel-а (IntersectionObserver).
Добавляйте pendingMs, чтобы короткие переходы не показывали спиннер.

const ReportsLink = () => {
  const router = useRouter()
  return (
    <Link
      to="/dashboard/reports"
      onMouseEnter={() => router.loadRoute('/dashboard/reports')}
    >
      Отчеты
    </Link>
  )
}

Loader best practices

Делайте loader чистой функцией: он не должен менять глобальные состояния.
loaderDeps помогает привязать loader к значениям из search, params или контекста.
После мутаций вызывайте router.invalidate({ to: '/dashboard/reports' }) — это перезапустит только связанные loader-ы.

const reportsRoute = dashboardRoute.createRoute({
  path: 'reports',
  loaderDeps: ({ search }) => search.status ?? 'all',
  loader: ({ loaderDeps, context }) =>
    context.api.reports.list({ status: loaderDeps }),
})

Prefetch и переходы

Link и router.navigate поддерживают params, search, hash, replace, viewTransition и mask.
Mask (например, { to: '/dashboard', search: true }) позволяет показать один layout во время загрузки другого (похоже на Remix).
router.navigate принимает throwOnError. Можно ловить ошибки и показывать toast вместо перехода.

await router.navigate({
  to: '/dashboard/reports/$reportId',
  params: { reportId },
  search: (prev) => ({ ...prev, focus: 'chart' }),
  mask: { to: '/dashboard', search: true },
  replace: true,
})

Отладка layout-дерева

В @tanstack/router-devtools есть вкладка Tree — отлично показывает, какие layout-уровни активны, и где pending.
Если маршрут не монтируется, убедитесь, что parent объявлен раньше (иначе getParentRoute вернет undefined).
Для крупных деревьев создайте routes/index.ts, где явно перечислены все дочерние маршруты и экспортирован routeTree.
Devtools можно условно подключать: process.env.NODE_ENV === 'development' && <TanStackRouterDevtools router={router} />.

Чек-лист

Каждый маршрут наследует правильный layout.
Общие guards вынесены на верхние уровни (beforeLoad у layout-узлов).
Ошибки и Pending-состояния покрывают тяжелые ветки + индикацию pendingMs.
Контекст передается через createRouter, layout-ы расширяют его при необходимости.
Типы компонентов/loader-данных не теряются (используем Route.useLoaderData).
Prefetch (loadRoute, usePrefetchRoute) настроен для дорогих веток.
Devtools включены в dev и выключены в prod.
Loader-ы детерминированы и синхронизированы с Query Client или invalidate.