Динамические параметры пути

export const Route = createRoute({
  getParentRoute: () => rootRoute,
  path: 'projects/$projectId/tasks/$taskId',
  parseParams: ({ projectId, taskId }) => ({
    projectId: Number(projectId),
    taskId: taskId as TaskId,
  }),
  stringifyParams: ({ projectId, taskId }) => ({
    projectId: projectId.toString(),
    taskId,
  }),
})

Множественные сегменты

• Используйте $ для одного сегмента, $...slug (splat) — для «остального» пути.
• Splat-сегмент обязан быть последним и отлично подходит для «истории» (/audit/$...path).
• Индексные маршруты (path: '/') рядом с динамическими родителями дают быстрый доступ к overview (projects/$projectId/).
• Для однотипных параметров (числа, UUID) храните единый parseParams helper и переиспользуйте через routeOptions.

Тонкости и лайфхаки

• Комбинируйте parseParams + beforeLoad, чтобы сразу редиректить на 404 при неверных значениях.
• В parseParams можно вычислить производные флаги (isArchived: projectId.startsWith('arch_')) и использовать их во всех дочерних компонентах.
• Loader получает уже приведённые типы — не тратьте время на повторные Number() в компонентах.
• Для SSR/инструментов типа e2e пригодится router.matchRoute('/projects/42'), чтобы убедиться, что params валидны ещё до рендера.

Search-параметры

const Route = createRoute({
  getParentRoute: () => rootRoute,
  path: 'reports',
  validateSearch: z.object({
    tab: z.enum(['summary', 'details']).default('summary'),
    from: z.coerce.date().optional(),
    to: z.coerce.date().optional(),
  }),
})

Использование в компонентах

const { tab, from } = Route.useSearch()
const params = Route.useParams()

useSearch возвращает типизированный объект; дефолты прописываются в схеме и работают и при SSR, и при навигации из кода.

Двусторонняя синхронизация

const navigate = Route.useNavigate()
const search = Route.useSearch()

const toggleTab = () =>
  navigate({
    search: (prev) => ({ ...prev, tab: prev.tab === 'summary' ? 'details' : 'summary' }),
    replace: true,
  })

• Обновляйте search функцией — это защищает от гонок при нескольких кликах.
• replace: true + дебаунс — лучшее решение для форм фильтрации, чтобы не засорять историю.
• Для сложных форм удобно использовать useSearchState (hook из Router), который возвращает [value, setValue] и упрощает связь с контролами.

Глобальные схемы поиска

• Layout-маршрут может объявить validateSearch, и все потомки автоматически наследуют схему.
• Потомок расширяет схему через parentSearchSchema.extend(...), сохраняя дефолты (page, pageSize).
• Если нужно переопределить дефолты, добавьте .transform((data) => ({ ...data, page: 1 })), либо напишите собственный mergeSearch.

Кастомный парсер/сериализатор

const Route = createRoute({
  getParentRoute: () => rootRoute,
  path: 'grid',
  parseSearch: (search) => ({
    page: Number(search.page ?? 1),
    tags: (search.tags?.split(',') ?? []).filter(Boolean),
  }),
  stringifySearch: ({ page, tags }) => ({
    page,
    ...(tags.length ? { tags: tags.join(',') } : {}),
  }),
})

• parseSearch удобен, когда часть параметров приходит не по схеме (напр., массив через tags=a,b); дополнительно можно запускать zod внутри.
• stringifySearch — лучшее место для удаления пустых значений: возвращайте объект без ключей, чтобы URL не разрастался.
• Можно комбинировать validateSearch (типизация) и stringifySearch (нормализация), если нужна и строгая проверка, и красивый URL.

Работа с URL вне компонентов

const url = router.buildLocation({
  to: '/blog/$postId',
  params: { postId: 7 },
  search: { highlight: true },
  hash: 'comments',
})
// → { href: '/blog/7?highlight=true#comments', pathname: '/blog/7', searchStr: '?highlight=true', ... }

• router.buildLink() вернёт готовые href/onClick для кастомных ссылок (например, внутри Markdown-рендера).

Типизированные ссылки

Используйте router.buildRouteTree() или router.routes (при автоматической генерации) для создания helpers:

routes.blog.post.$postId({ postId: 8, search: { preview: true } })

• Передавайте такие helpers в дизайн-систему, чтобы <ButtonLink route={routes.blog.post.$postId} params={{ postId: 8 }} /> сам формировал URL.
• Лениво загруженные страницы можно прогреть через routes.blog.post._ctx.loader?.preload({ postId }), чтобы пользователь мгновенно увидел данные.

Hash и состояние

• hash: 'comments' — добавляет #comments.
• state в navigate позволяет передавать произвольные данные (не сериализуются в URL).
• Храните во state только непродолжительные данные (fromModal: true). При обновлении страницы state исчезает, поэтому критичные значения — только в search.

Лучшие практики валидации

1. Применяйте zod/valibot или кастомную функцию.
2. Возвращайте значения в нужных типах (Date, number), чтобы компоненты были максимально «тупыми».
3. Всегда задавайте дефолты — так useSearch() никогда не вернёт undefined.
4. Используйте shouldReload/loaderDeps, чтобы чётко описать, какие параметры должны перезагружать данные.
5. Логируйте ошибки валидации (Sentry breadcrumb, analytics), чтобы понимать, какие URL ввёл пользователь.
6. Общие схемы держите в shared-пакете и переиспользуйте в SSR/API — меньше расхождений между клиентом и сервером.

Переиспользуемые схемы и композиция

const paginationSearch = z.object({
  page: z.coerce.number().int().positive().default(1),
  pageSize: z.coerce.number().int().positive().max(200).default(25),
})

const filtersSearch = paginationSearch.extend({
  statuses: z.array(z.enum(['open', 'closed', 'draft'])).default(['open']),
})

export const TicketsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: 'tickets',
  validateSearch: filtersSearch,
})

• Один и тот же объект схемы можно импортировать и в клиенты API (например, tRPC), чтобы гарантировать одинаковые правила.

Пример: таблица с фильтрами и колонками

const navigate = Route.useNavigate()
const search = Route.useSearch()

const toggleColumn = (id: string) =>
  navigate({
    search: (prev) => ({
      ...prev,
      columns: { ...prev.columns, [id]: !prev.columns?.[id] },
    }),
    replace: true,
  })

• Валидация может ограничить ключи колонок: z.record(z.enum(columnIds), z.boolean()).default({}).
• Сохраняйте последние фильтры в localStorage, а при монтировании вызывайте router.navigate({ to: Route.to, search: restoreFilters(), replace: true }), чтобы восстановить пользовательский контекст.

Отладка и диагностика

• router.parseLocation(window.location) показывает, как URL интерпретирован (params/search/hash).
• В dev-режиме включите router.options.defaultPreload = 'intent', чтобы заранее валидировать params при наведении на ссылки.
• router.subscribe('onRouteError', (error) => …) помогает ловить ошибки валидации и отображать дружелюбные сообщения.
• Для unit-тестов удобно использовать router.__store.getState().location и проверять, что search/params сериализуются как ожидается.

Чек-лист

• Все динамические сегменты имеют parse/stringify.
• Search-параметры описаны схемой и покрыты дефолтами.
• Навигация использует типизированные helpers/route tree.
• Hash используется только для якорей, state — для эфемерных данных.
• Splat-сегменты не конфликтуют с соседними путями.
• stringifySearch удаляет пустые значения и сортирует ключи.
• Валидация переиспользуется на клиенте и сервере.
• Ошибочные URL приводят к redirect или осмысленному экрану.