Зачем нужны Routing Trees

В TanStack Router v1 маршруты описываются как дерево. Каждый узел определяет:

• путь (path) или индикатор индекса (index),
• родителя (getParentRoute),
• опции загрузки данных (loader, beforeLoad, pendingComponent),
• контекст (context) и метаданные (staticData, meta).

Такой подход даёт:

1. Типобезопасные ссылки: параметры пути и поиска выводятся из дерева.
2. Статический анализ для code splitting, SSR, prefetch и дев-обновлений.
3. Общий контекст между ветками (layout делится session, queryClient, theme и т. д.).
4. Автоматический linkBuilder с автодополнением и подсказками IDE.
5. Возможность подключать DevTools и визуально видеть, какие узлы загружены/ожидают.

Лайфхак: если видите странные ошибки типов в ссылках, просто переимпортируйте routeTree — генератор прогоняет весь типовой вывод и подсвечивает конфликты путей ещё до runtime.

Базовый пример дерева

// src/routes/routeTree.gen.ts (генерируется плагином)
import { Route as rootRoute } from './__root'
import { Route as indexRoute } from './index'
import { Route as blogRoute } from './blog'
import { Route as blogPostRoute } from './blog.$postId'

export const routeTree = rootRoute.addChildren([
  indexRoute,
  blogRoute.addChildren([blogPostRoute]),
])

Когда собирать дерево вручную

• Проекты без файловой генерации (storybook, playground) — создайте routeTree руками.
• Интеграционные тесты: соберите дерево только из нужных веток и моков context.
• Микрофронты: каждая команда публикует свою ветку как пакет и «вкручивает» её в общее дерево на стадии сборки.

Структура layout-веток

// routes/blog.tsx
import { Outlet, createRoute } from '@tanstack/react-router'
import { Route as rootRoute } from './__root'

export const Route = createRoute({
  getParentRoute: () => rootRoute,
  path: 'blog',
  beforeLoad: ({ context }) => {
    if (!context.session) {
      throw new Redirect({ to: '/login', search: { next: '/blog' } })
    }
    return { theme: context.theme ?? 'light' }
  },
  component: () => (
    <BlogLayout>
      <Suspense fallback={<BlogSkeleton />}>
        <Outlet />
      </Suspense>
    </BlogLayout>
  ),
})

Лайфхаки:

• beforeLoad исполняется один раз на заход и кэширует результат, пока родитель не сброшен — идеально для проверки прав.
• Layout можно сделать lazy, если импортировать через createLazyRoute.
• Дочерние маршруты могут читать контекст родителя через Route.useRouteContext({ from: blogRoute.id }), не пробрасывая пропсы.

Индексные маршруты

export const Route = createRoute({
  getParentRoute: () => blogRoute,
  path: '/',
  component: () => <PostsList />,
})

Индексы не имеют собственного сегмента URL, поэтому:

• Используйте addIndexRoute() для краткости — у него нет path, и ссылки к нему не требуют params.
• В больших layout-ах индексы удобно применять для дефолтных вкладок (например, /settings → вкладка «Profile»).
• Не путайте индекс с пустым путём '': индекс срабатывает только когда родитель полностью совпал без дополнительных сегментов.

Динамические сегменты

export const Route = createRoute({
  getParentRoute: () => blogRoute,
  path: '$postId',
  parseParams: (raw) => ({
    postId: Number(raw.postId),
  }),
  stringifyParams: ({ postId }) => ({
    postId: postId.toString(),
  }),
  component: PostView,
})

Советы:

• Всегда приводите типы в parseParams (числа, UUID, даты). Это избавляет от Number(searchParams.get(...)) по всему коду.
• Для сложных параметров используйте zod или valibot, чтобы возвращать безопасные структуры.
• Необязательные сегменты пишутся '$postId?'. В parseParams возвращайте дефолт, чтобы не ловить undefined в компонентах.

Вычисляемые пути и search-схемы

• Сегменты можно комбинировать: path: '$category/$slug'.
• validateSearch наследуется вниз — задайте базовую схему на layout и расширяйте в дочках.

import { z } from 'zod'

export const Route = createRoute({
  getParentRoute: () => blogRoute,
  path: '$category/$slug',
  validateSearch: z.object({
    draft: z.boolean().default(false),
    cursor: z.string().optional(),
  }),
  loader: async ({ params, context }) => {
    const queryKey = ['post', params.category, params.slug]
    await context.queryClient.ensureQueryData({
      queryKey,
      queryFn: () => fetchPost(queryKey),
    })
    return { queryKey }
  },
})

Лайфхак: используйте router.navigate({ search: prev => ({ ...prev, cursor: nextCursor }) }) — тогда типы search и мемоизация гарантированы.

Плагины генерации дерева

@tanstack/router-plugin собирает дерево из файлов по шаблону routes/**/*.tsx.

Правила:

1. Каждый файл экспортирует Route.
2. Имя файла = путь (blog.$postId.lazy.tsx → blog/$postId).
3. Файл __root.tsx обязателен (глобальные провайдеры, error boundaries).

Полезные мелочи:

• Файлы с .lazy.tsx автоматически помечаются как lazyRouteComponent.
• Можно комбинировать routeContext + loader прямо в файле, плагин подхватит экспорт.
• Включите watch: true, чтобы при добавлении файла routeTree.gen.ts пересобирался мгновенно (и коммитьте этот файл, иначе типы в CI «поедут»).

Советы по проектированию дерева

• Держите глубину ≤5 уровней. Если глубже — подумайте о вложенных layout-ах с Outlet.
• Группируйте по доменам (/app, /marketing, /admin). Так проще выключать крупные ветки флагами.
• Auth лучше ставить на уровне layout-а (beforeLoad + context.session). Не дублируйте проверки в каждом листе.
• Создайте хелпер routeTree.buildRouteTree() и экспортируйте routes для ссылок вне React:

  export const routes = router.routeTree.buildRouteTree()
  routes.blog.post.$postId({ postId: 42 }) // → /blog/42
  

• Если нужно организовать поддомены (например, :team.myapp.com), объявите корень path: '$teamId' и используйте router.basepath.

Route Context и шаринг состояния

export const Route = createRoute({
  getParentRoute: () => blogRoute,
  path: '$postId',
  beforeLoad: async ({ context, params }) => {
    const post = await context.api.getPost(params.postId)
    return { post }
  },
  component: () => {
    const { post } = Route.useRouteContext()
    return <PostView post={post} />
  },
})

• beforeLoad выполняется до loader и может кинуть Redirect/Error, если данных нет.
• Контекст родителя доступен детям через Route.useRouteContext({ from: parentRoute.id }).
• Не кладите туда гигантские объекты, если они могут меняться каждую секунду — это триггерит ререндер всех потомков.

Интеграция с React Query

export const Route = createRoute({
  getParentRoute: () => blogRoute,
  path: '$postId',
  loader: ({ context, params }) =>
    context.queryClient.ensureQueryData({
      queryKey: ['post', params.postId],
      queryFn: () => fetchPost(params.postId),
    }),
  component: () => {
    const { params } = Route.useRoute()
    const { data } = useQuery(['post', params.postId], { enabled: false })
    return <PostView post={data} />
  },
})

• ensureQueryData работает одинаково на сервере и клиенте, поэтому гидратация прозрачна.
• В onBeforeUnload можно отменять долгие запросы через router.store.
• Для прогрева кэша навешивайте router.preloadRoute на onPointerEnter ссылок.

Lazy-маршруты и code splitting

• Переименуйте файл в *.lazy.tsx и экспортируйте Route = createLazyRoute(...).
• Внутри loader можно импортировать код await import('./chunks/post') — роутер автоматически покажет pendingComponent.
• Для больших layout-ов добавляйте pendingComponent и pendingMs, чтобы избегать дерганий UI.

Типобезопасные ссылки и навигация

router.navigate({
  to: blogPostRoute.to,
  params: { postId: 1 },
  search: { highlight: 'comments' },
  mask: { to: '/blog', search: true }, // user видит маску
  replace: false,
})

• createFileRoute и createLazyFileRoute генерируют to и fullPath, которые гарантированно совпадают с деревом.
• useLinkProps даёт готовые href/onClick, плюс опции preload, preloadDelay, pending.
• mask помогает прятать настоящие query-параметры (например, ?cursor=) за более чистым URL.

DevTools и диагностика

• Включите routerDevtools() — вкладка Route Tree показывает pending/loader/error по каждому узлу.
• В DevTools видно, какой search наследуется. Если loader перезапускается слишком часто, смотрите вкладку Invalidations.
• Подсветка Prefetch помогает понять, какие ссылки триггерят router.preloadRoute.

Типичные подводные камни

• Дублирующиеся пути: два файла с одинаковым именем → конфликт. Плагин ругается, но если дерево собираете вручную, добавьте assertRouteTree.
• Необъявленные search-поля: без validateSearch они приезжают как any и ломают типы ссылок. Создайте базовую схему хотя бы для locale.
• Вечные pending: если loader возвращает defer, убедитесь, что компонент обёрнут в Suspense.
• Глобальные сторы: не кладите zustand/redux в context, прокидывайте провайдером на уровне __root.

Чек-лист

• У каждого маршрута явный getParentRoute.
• Layout-ветки рендерят Outlet и/или useRouteContext.
• Все динамические сегменты имеют parse/stringify.
• Индексные маршруты описаны явно (или через addIndexRoute).
• validateSearch покрывает критичные query-параметры.
• Prefetch настроен для горячих ссылок (preload/ensureQueryData).
• DevTools не показывает конфликтов путей и «красных» loader-ов.
• routeTree.gen.ts синхронизирован с файловой системой.

Дополнительные ресурсы

• Документация v1: https://tanstack.com/router/v1/docs
• Примеры: examples/react/file-based-routing, examples/react/start-client-router-ssr
• Видео «Thinking in Route Trees» от Tanner Linsley — отличный источник паттернов и анти-паттернов.