# react-router-dom vs TanStack Router

## Context

Проект использует **react-router-dom v6** для клиентской маршрутизации. Требуется route-level code splitting (lazy loading). Также стоит вопрос о типобезопасности роутов и интеграции с уже используемым TanStack Query.

## Candidates

### react-router-dom v6 (текущий)

- Стабильный стандарт де-факто
- Декларативный API: `<Routes>`, `<Route>`, `<Link>`
- lazy loading через `React.lazy()` + `<Suspense>` — добавляется вручную
- Search params: `useSearchParams()` — без типизации, строками
- Параметры: `useParams()` — без типизации
- Нет встроенных loaders / prefetching
- Нет генерации типов
- Размер: ~8KB gzip
- Нет нативной интеграции с TanStack Query

### TanStack Router

- **Генерация RouteTree**: полная типобезопасность путей, параметров, search params
- **Search params с Zod**: декларативная валидация и парсинг (Zod уже используется в проекте)
- **Route loaders**: prefetching данных ДО рендера компонента, кеширование
- **Code splitting built-in**: каждый роут ленивый по умолчанию, без `React.lazy` boilerplate
- **Pending/Error/NotFound boundaries** на уровне роута
- **Интеграция с TanStack Query**: loaders могут вызывать `queryClient.fetchQuery()` напрямую
- **File-based routing**: чище организация кода (опционально)
- Файл роута = route + component + loader + error/loading states
- Размер: ~3-4KB gzip
- 1.2B+ total downloads, 20M+ weekly

## Comparison

| Критерий | react-router-dom v6 | TanStack Router |
|----------|---------------------|-----------------|
| Типизация путей | ❌ строки | ✅ генерация |
| Типизация params | ❌ `useParams()` без типа | ✅ autocomplete |
| Search params typing | ❌ `useSearchParams()` строки | ✅ Zod-схемы |
| Lazy loading | ⚠️ React.lazy + Suspense | ✅ built-in |
| Loaders / prefetch | ❌ нет | ✅ |
| TanStack Query synergy | ❌ | ✅ native |
| Bundle size | ~8KB gzip | ~3-4KB gzip |
| Migration effort | — | средняя |
| Learning curve | низкая | средняя |

## Verdict: TanStack Router

**Рекомендуется TanStack Router**:

1. **Типобезопасность** — генерация типов исключает класс багов (опечатки в путях, невалидные search params)
2. **Code splitting без boilerplate** — каждый роут грузится лениво автоматически, не нужно `React.lazy`
3. **Синергия с TanStack Query** — уже используется в проекте; loaders дают prefetching до рендера
4. **Zod** — уже используется в проекте для валидации форм; Router использует Zod для search params

Минусы: требуется переписывание всех роутов, компонентов навигации (`Link`, `useNavigate`) и тестов (`MemoryRouter` → `createMemoryRouter`). Каждый переезд — отдельная задача с тестированием.