Типобезопасность маршрутизатора

После создания router объявите модульное расширение:

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

Так Link, useNavigate, useRouterState будут знать про params, search, context.

Тонкости:

• Держите декларацию рядом с экспортом router. IDE быстрее подхватывают *.d.ts, если файл импортируется хотя бы раз.
• В монорепах делайте единый types/router.d.ts и добавляйте его в tsconfig.references, чтобы не было дублирования Register.
• После миграции на v1 удалите старые декларации для @tanstack/router, иначе Register['router'] превратится в never.

Типизация компонентов маршрутов

type RouteComponentProps<T extends AnyRoute> = {
  route: T
  useLoaderData: () => LoaderData<T>
}

export function PostPage({
  useLoaderData,
}: RouteComponentProps<typeof Route>) {
  const post = useLoaderData()
}

Лайфхаки:

• Используйте RouteById<AppRouter, 'posts/$postId'> для layout-компонентов — так вы получите тип params и loaderData сразу.
• Создайте HOC withRoute(RouteComponent) который принимает AnyRoute и возвращает компонент с пропом route. TypeScript сохранит конкретные поля staticData, context.
• В useLoaderData указывайте typeof Route.loader через Awaited<ReturnType<typeof Route.loader>>, чтобы не дублировать структуры данных.

Контекст и createRootRouteWithContext

interface RouterContext {
  queryClient: QueryClient
  session: Session | null
}

export const rootRoute = createRootRouteWithContext<RouterContext>()({
  beforeLoad: ({ context }) => {
    invariant(context.session, 'Auth required')
  },
})

• createRootRouteWithContext гарантирует, что дочерние маршруты увидят context.
• Передавайте context в createRouter({ context }). В тестах подставляйте фейковый объект; TS проследит за обязательными полями.
• Добавляйте satisfies RootRouteOptions<RouterContext> к объекту опций, чтобы IDE подсказывала доступные свойства (beforeLoad, notFoundComponent, meta).

Схемы параметров и поиска

• Для parseParams отдавайте брендовые типы (type TenantId = Brand<string,'TenantId'>), чтобы не перепутать userId и orgId.
• В validateSearch используйте zod/valibot + satisfies RouteValidateSearchOptions, чтобы не потерять сигнатуру.

Пример:

const searchSchema = z.object({
  page: z.coerce.number().int().positive().default(1),
  tags: z.array(z.string()).catch([]),
})

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

• Теперь useSearch({ from: postsRoute.id }) подскажет оба поля, а navigate({ to: postsRoute.to, search: { page: '1' } }) подсветится как ошибка.
• Необязательные параметры описывайте через z.preprocess → undefined, иначе Router решит, что поле обязательно.

Референсы маршрутов и helpers

export const routes = router.buildRouteTree()
routes.blog.post.$postId({ postId: 1 }).to

buildRouteTree() создает объект с типизированными to, fullPath, params, useLoaderData, useStaticData.

Полезные приёмы:

• routes.org.$orgId.useParams() — автодополнение параметров, удобно для shared-хуков (useCurrentOrg(routes.org.$orgId)).
• routes.toArray() пригодится в тестах: можно пробежаться по всем маршрутам и убедиться, что staticData содержит title.
• route.mask({ params, search }) помогает строить ссылки без ручных шаблонов.

Общие хуки и утилиты

export const useRouteParams = <T extends AnyRoute>(route: T) => route.useParams()

export function useTypedNavigate<TRoute extends AnyRoute>(route: TRoute) {
  const navigate = useNavigate()
  return (opts?: Parameters<typeof route.navigate>[0]) =>
    navigate({ ...opts, to: route.to })
}

• Соберите библиотеку useRouteSearch, useRouteStaticData, useRouteLoaderData — редактор сохранит типы за счёт generic.
• В SSR оборачивайте хуки в useMemo(() => route.useLoaderData(), [route.id]), чтобы не потерять неизменяемость (TS понимает зависимости).

Ленивые маршруты и code splitting

• Используйте lazyRouteComponent(() => import('./page')) satisfies RouteComponent.
• Для loaders/метаданных экспортируйте type Module = Awaited<typeof import('./page')> и используйте Module['loader'].
• Если компонент экспортируется по умолчанию, пишите lazyRouteComponent(() => import('./page').then((m) => ({ default: m.Page }))) — тип RouteComponent сохранится.
• lazyRoute + ValidateSearch → TS проверит схему ещё до загрузки файла.

Навигация, prefetch и guards

• Link принимает generic RouteIds: Link<RouteIds, { search: Search }> запрещает неправильные параметры.
• useMatchRoute:

  const matchRoute = useMatchRoute()
  const match = matchRoute({ to: routes.dashboard.to, search: { tab: 'stats' } })
  if (match) {
  console.log(match.params) // типизированы
  }
  

• Для prefetch используйте router.preloadRoute({ to: route.to, params }) — параметры выводятся из route.
• Guard можно описать как type Guard = (opts: RouteGuardOptions<AppRouter>) => Promise<void> и применять через beforeLoad.

ESLint и tsconfig

• "moduleResolution": "bundler" (Vite) или "nodenext" (SSR) помогут корректно резолвить модульные пути Router.
• Включите "types": ["@tanstack/react-router"], если TS не видит расширение.
• Полезные правила: @typescript-eslint/consistent-type-imports, кастомное tanstack-router/no-raw-path (запрещает to="/foo"), tanstack-router/require-validate-search.
• Для server actions включайте "verbatimModuleSyntax": true, чтобы не было дубликатов import Route.

Модульные утилиты и DI

src/lib/router.ts:

export const router = createRouter({ routeTree, context })
export type AppRouter = typeof router
export type RoutePaths = keyof AppRouter['flatRoutes']
export type RouteIds = AppRouter['routeTree']['id']
export type RouterRoute<T extends RouteIds> = RouterRouteById<AppRouter, T>

• Экспортируйте AppRouter и используйте в DI-контейнере (container.register(AppRouterToken, router)).
• В тестах тип RouterRoute<'posts/$postId'> помогает создать фиктивные данные без обращения к реальному Router.

Тестирование маршрутов

• await router.load() с memoryHistory для unit-тестов loaders.
• Для компонентов — renderWithRouter(<Link ... />, { router }).
• Мокауте context и dehydrateRouter(router) для e2e.
• Snapshot-тест expect(router.state.matches).toMatchInlineSnapshot() фиксирует search, status, context.
• Проверяйте loader так:

  const loader = (opts: LoaderFnOpts) => fetchData(opts)
  const route = createFileRoute('/x')({
  loader: loader satisfies LoaderFn<LoaderFnOpts, LoaderResult>,
  })
  

Логирование, метрики, Observability

• type NavigationMeta = RouterState['pendingMatches'][number]['meta'] — пригодится для метрик загрузки.
• В beforeLoad возвращайте Promise<void> и логируйте context.logger.debug({ routeId }) — типы routeId и params будут проверены.
• Интеграция с OpenTelemetry: храните traceId в context, а в loader описывайте loader: ((opts) => instrument(opts, realLoader)) satisfies LoaderFn.

Лучшие практики

1. Избегайте строковых путей — используйте routes.* или RouteById.
2. Все значения search/params локализуйте в одном helper (легче рефакторить).
3. Проверяйте опции маршрута через satisfies RouteOptions.
4. Выносите типы loaders: type LoaderData = Awaited<ReturnType<typeof loader>>.
5. beforeLoad и action описывайте через satisfies, чтобы не потерять context.
6. Передавайте select в route.useLoaderData({ select }), чтобы типы соответствовали выбранному полю.
7. Для multi-tenant проектов используйте брендовые типы TenantId, AccountId и возвращайте их в parseParams.
8. Создавайте expectType<RouteById<'known/id'>>() в тестах — IDE гарантирует, что ID существует.

Чек-лист

• Router зарегистрирован в декларации модуля.
• Контекст описан через createRootRouteWithContext и прокинут в createRouter.
• Компоненты используют RouteComponentProps, RouteById или маршрутовые хуки.
• Схемы params/search валидируются и возвращают брендовые типы.
• Helpers routes.*, useTypedNavigate заменяют строковые пути.
• Lazy-модули типизированы через satisfies, loaders/actions проверяются.
• Тесты покрывают router.load, renderWithRouter, snapshot router.state.
• Логирование/метрики получают данные из типизированных meta.