Причины использовать ленивые маршруты

• Сокращение initial JS: каждая ветка дерева маршрутов грузится только при первом заходе.
• HTTP/2 friendly: бандлер разбивает код по маршрутам, и браузер скачивает их параллельно.
• Контроль доступа: sensitive экраны (админка) не попадут в кэш до прохождения beforeLoad.
• Переиспользование роутов на нескольких shell’ах — клиент скачивает минимум общего кода и layout.
• SSR/SSG: при router.dehydrate() попадает только статика, сами чанки подтянутся при гидрации.

Когда ленивость вредна

• Критический путь (landing, login, shared layout) должен оставаться в основном чанке.
• Если в маршруте много above-the-fold UI, пользователю будет заметно мигание fallback’а.
• При очень мелких страницах выигрыш в размере не стоит роста waterfall — лучше объединить.

Быстрый обзор API v1

import { createLazyRoute } from '@tanstack/react-router'
import { Route as dashboardRoute } from './dashboard'

export const Route = createLazyRoute({
  getParentRoute: () => dashboardRoute,
  path: 'reports',
  pendingComponent: () => <Spinner />,        // показывается пока грузится модуль
  errorComponent: (props) => <ErrorBox {...props} />,
  beforeLoad: async ({ context }) => {
    await context.auth.requireRole('analyst')
  },
  loader: async (opts) => {
    const { loader } = await import('./reports.loader')
    return loader(opts)
  },
  component: async () => {
    const { ReportsPage } = await import('./reports.component')
    return <ReportsPage />
  },
})

• component и loader могут быть независимыми чанками — полезно, когда нужно прогреть данные заранее через router.loadRoute.
• pendingComponent и errorComponent хранятся рядом с маршрутом, что избавляет от обязательного Suspense на layout.
• beforeLoad выполняется до подгрузки модуля компонента. Можно отменить переход, тем самым не тратить трафик.

Разделение файлов по соглашениям

• *.route.tsx + *.lazy.tsx: первый описывает статическую часть маршрута, второй экспортирует ленивое содержимое. ```tsx // settings.lazy.tsx import { createFileRoute } from ‘@tanstack/react-router’

export const Route = createFileRoute(‘/dashboard/settings’).createRoute({ component: () => import(‘./SettingsPage’).then((m) => ), pendingComponent: () => , })

- `createFileRoute` автоматически добавляет `Route.lazy()` helper, его можно вызвать для динамического импорта прямо из `routeTree.gen.ts`.
- Не забывайте давать именованные экспорты страницам/loader'ам — tree-shaking эффективнее и не будет промахов с default-export.

## Prefetch и управление чанками
```tsx
<Link
  to="/dashboard/reports"
  preload="intent"
  preloadDelay={120}       // предотвращает спам запросов при быстрых hover'ах
  preloadGcMaxAge={60_000} // держим модуль в кеше минуту
/>

• preload="render" подгрузит маршрут сразу при рендере ссылки (нужно для критичных переходов из меню).
• Программно: router.preloadRoute({ to: '/dashboard/reports', search: { tab: 'weekly' } }) — запускает и beforeLoad, и loader, чтобы данные лежали в routerState.matches.
• Для мобильных жестов удобно слушать onTouchStart и вызывать router.preloadRoute с задержкой 50–80 мс.
• router.loadMatches(routes) пригодится на dashboard, где надо прогреть несколько ленивых веток параллельно.

Разделение loaders и побочные импорты

• Тяжелые зависимости (chart.js, mapbox) подгружайте внутри loader: const [{ renderChart }, data] = await Promise.all([import('./chart.utils'), fetchData()]).
• Loader можно разбить на loader + defer() (React 18). Танстековский loader может вернуть defer, а Suspense в layout покажет pendingComponent.
• beforeLoad ➝ проверка прав без загрузки UI. loader ➝ fetch + dynamic import util-функций. component ➝ только React-дерево, без бизнес-логики.

Совместимость с Suspense

const DashboardShell = () => (
  <Suspense fallback={<Spinner />}>
    <Outlet />
  </Suspense>
)

• В TanStack Router v1 Suspense срабатывает только если ленивый маршрут возвращает Promise. pendingComponent даст более granular пер-маршрут fallback, а Suspense — общий layout fallback.
• Если вам нужен skeleton внутри страницы, экспортируйте Route.options.pendingComponent из того же lazy-модуля, чтобы не тащить компоненты в основной бандл.

SSR, SSG и hydrate

• На сервере router.dehydrate() не будет встраивать содержимое ленивых чанков — только данные loader’ов. Поэтому клиенту нужен router.hydrate() с тем же routeTree.
• Для edge-фреймворков (Next, Remix) важно сделать await router.loadRoute() перед renderToPipeableStream, чтобы скрыть network waterfall после гидрации.
• Если используете startTransition + router.navigate, старайтесь вызвать router.preloadRoute при наведении, иначе Suspense будет мигать после SSR.

Оптимизация сборки

• Vite: build.rollupOptions.output.manualChunks → объединяйте редкие admin маршруты в один admin-[hash].js.
• Webpack: /* webpackChunkName: "reports" */ внутри dynamic import, чтобы DevTools не показывали загадочные id.
• Next.js / Remix: TanStack Router живет в client component, но code splitting все равно работает, потому что dynamic import обрабатывается бандлером.
• Bundle Analyzer: запускайте vite build --analyze или ANALYZE=true next build, чтобы свериться, что ленивые чанки реально отделились.
• У router.devtools есть вкладка Chunks: смотрите, какие маршруты уже загружены, можно руками очищать через router.invalidateRoute.

Лайфхаки

1. Навесьте preload="intent" на все Link, которые видны дольше 1 с — пользователи не заметят задержку.
2. В layout храните const { isFetching } = useRouterState({ select: (s) => s.isFetching }), чтобы показать глобальный progress bar во время ленивой загрузки.
3. Переиспользуйте ленивые маршруты между проектами: createLazyRoute можно обернуть в фабрику, которая принимает зависимости (api, auth).
4. Делайте eager-import для очень маленьких утилит, иначе потеряете выгоду от tree-shaking (Rollup создаст слишком много чанков <1 кБ).
5. Старайтесь делить не только страницы, но и большие layout’ы (settings/layout.lazy.tsx) — тогда вложенные children будут грузиться мгновенно.
6. Для A/B тестов оборачивайте ленивый компонент в routeContext, чтобы подменять импортируемый модуль в runtime.

Чек-лист

• Маршруты с большим UI вынесены в createLazyRoute / .lazy.tsx.
• Настроены pendingComponent + errorComponent для каждого ленивого уровня.
• Предзагрузка организована по hover/touch/visible стратегиям.
• Loader и компонент разделены, тяжелые зависимости подгружаются динамически.
• Проверки доступа живут в beforeLoad, чтобы не качать лишний код.
• Аналитика размеров чанков подключена (devtools / analyzer).
• SSR поток гарантирует router.loadRoute перед рендером.