Интеграция с Next.js

TanStack Router предоставляет мощные возможности маршрутизации, включая декларативные маршруты, динамические сегменты и вложенные структуры. Для интеграции с Next.js первым шагом является установка пакета:

npm install @tanstack/router

После установки создается основной файл конфигурации маршрутизатора, например router.ts, где описываются маршруты и их структура.

import { createRouter, route } from '@tanstack/router'

const rootRoute = route({
  path: '/',
  component: RootLayout,
})

const aboutRoute = route({
  path: '/about',
  component: AboutPage,
})

export const router = createRouter({
  routeTree: rootRoute.addChildren([aboutRoute])
})

Главная особенность интеграции с Next.js заключается в использовании TanStack Router в сочетании с системой серверного рендеринга (SSR) и маршрутизацией страниц. Для этого маршрутизатор оборачивается в компонент в _app.tsx:

import { RouterProvider } from '@tanstack/router'
import { router } from '../router'

export default function App({ Component, pageProps }) {
  return 
}

Работа с динамическими маршрутами

TanStack Router поддерживает динамические сегменты, что позволяет строить маршруты с параметрами:

const userRoute = route({
  path: '/users/$userId',
  component: UserPage,
  loader: async ({ params }) => {
    const response = await fetch(`/api/users/${params.userId}`)
    return response.json()
  },
})

В Next.js динамические сегменты соответствуют [param] в файловой структуре страниц, однако TanStack Router позволяет управлять ими декларативно и извлекать данные через loader.

Вложенные маршруты и Layouts

Вложенные маршруты создаются с помощью метода addChildren, что упрощает создание многоуровневых интерфейсов. Например:

const dashboardRoute = route({
  path: '/dashboard',
  component: DashboardLayout,
})

const dashboardAnalyticsRoute = route({
  path: 'analytics',
  component: AnalyticsPage,
})

dashboardRoute.addChildren([dashboardAnalyticsRoute])

Внутри Next.js это позволяет использовать Outlet для рендеринга дочерних компонентов в родительском layout:

import { Outlet } from '@tanstack/router'

export function DashboardLayout() {
  return (
    

      
      

        
      

    

  )
}

Предзагрузка данных и серверный рендеринг

TanStack Router поддерживает предзагрузку данных с помощью loader, что идеально подходит для SSR в Next.js:

export async function getServerSideProps(context) {
  const data = await router.load({
    url: context.resolvedUrl
  })
  return { props: { data } }
}

Это позволяет полностью синхронизировать состояние маршрутов с серверной логикой, обеспечивая быструю загрузку страниц и корректный рендеринг на стороне сервера.

Навигация и управление состоянием маршрута

Навигация осуществляется через хук useRouter:

import { useRouter } from '@tanstack/router'

function NavButton() {
  const router = useRouter()
  return (
    
  )
}

useRouter предоставляет методы navigate, back, reload и доступ к текущим параметрам маршрута, что упрощает работу с динамическим контентом и состоянием URL.

Обработка ошибок и fallback страницы

Для обработки ошибок TanStack Router использует errorComponent на уровне маршрута:

const errorRoute = route({
  path: '*',
  component: ErrorPage,
})

Это обеспечивает единый механизм обработки несуществующих маршрутов и ошибок загрузки данных, интегрируясь с Next.js Error Boundaries.

Интеграция с API маршрутизацией Next.js

TanStack Router может работать в связке с API-роутами Next.js. Например, для страницы пользователей:

export async function loader({ params }) {
  const res = await fetch(`/api/users/${params.userId}`)
  if (!res.ok) throw new Error('User not found')
  return res.json()
}

В Next.js API-роуты остаются стандартными, но TanStack Router обеспечивает единый интерфейс загрузки данных и управление состоянием маршрутов.

Поддержка SSR и SSG

TanStack Router полностью совместим с getServerSideProps и getStaticProps. С помощью router.load можно получать данные для статической генерации страниц:

export async function getStaticProps() {
  const data = await router.load({ url: '/dashboard/analytics' })
  return { props: { data } }
}

Это позволяет использовать преимущества маршрутизатора без потери возможностей статической оптимизации Next.js.

Работа с middleware и guards

TanStack Router поддерживает перехват навигации через beforeLoad или глобальные middleware:

router.beforeLoad(({ params }) => {
  if (!isAuthenticated()) {
    return router.navigate('/login')
  }
})

Это обеспечивает защиту маршрутов, аналогичную getServerSideProps или middleware в Next.js, но с декларативным синтаксисом внутри самого маршрутизатора.

Использование состояния маршрута

TanStack Router хранит состояние маршрута, что позволяет синхронизировать UI с URL без лишнего хука useState:

const { params, route } = useRouter().current

Параметры, query и состояние loader автоматически доступны на каждом уровне вложенного маршрута, упрощая построение сложных интерфейсов с зависимыми данными.

Оглавление