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

• Сокращение 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 { createFileRoute } from '@tanstack/react-router'

// routes/dashboard/reports.tsx (critical config)
export const Route = createFileRoute('/dashboard/reports')({
  loader: ({ context }) => context.api.reports.list(),
})

import { createLazyFileRoute } from '@tanstack/react-router'

// routes/dashboard/reports.lazy.tsx (non-critical config)
export const Route = createLazyFileRoute('/dashboard/reports')({
  component: ReportsPage,
  pendingComponent: () => <Spinner />,
  errorComponent: (props) => <ErrorBox {...props} />,
})

• Для file-based роутинга это базовый способ code splitting в 2026: *.tsx + *.lazy.tsx.
• beforeLoad и loader остаются в “критическом” файле, чтобы preloading мог стартовать без лишнего waterfall.

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

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

export const Route = createLazyFileRoute(‘/dashboard/settings’)({ component: SettingsPage, pendingComponent: () => , })

- Для Vite-проектов включайте `autoCodeSplitting: true` в `@tanstack/router-plugin/vite`, чтобы разделение критического/некритического кода происходило автоматически.
- Не забывайте давать именованные экспорты страницам/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, чтобы переход был мгновеннее.
• Для мобильных жестов удобно слушать onTouchStart и вызывать router.preloadRoute с задержкой 50–80 мс.
• Если нужен только JS-бандл, используйте router.loadRouteChunk(route) (без загрузки данных).

Разделение 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.load() перед 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. Переиспользуйте ленивые маршруты между проектами: createLazyFileRoute/createLazyRoute можно обернуть в фабрику.
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, чтобы не качать лишний код.
• Для file-based routing проверен autoCodeSplitting в конфиге плагина.
• Аналитика размеров чанков подключена (devtools / analyzer).
• SSR поток гарантирует router.load() перед рендером.