Использование с Vite

Для начала интеграции TanStack Router в проект на Vite необходимо создать новый проект или использовать существующий. Vite обеспечивает быстрый старт и поддерживает современные стандарты ES-модулей, что идеально подходит для работы с TanStack Router.

npm create vite@latest my-app --template react
cd my-app
npm install
npm install @tanstack/router

После установки TanStack Router необходимо создать базовую структуру маршрутов. Основная единица маршрутизации — объект Route. В Vite и React это делается через компонент RouterProvider и конфигурацию маршрутов.

Создание маршрутов

Маршруты описываются с помощью объектов, где ключевыми свойствами являются path, component и children. Пример базового маршрута:

import { createRouter, RouterProvider, Route } from '@tanstack/router';
import Home from './pages/Home';
import About from './pages/About';

const router = createRouter({
  routeTree: Route({
    path: '/',
    component: () => <Home />,
    children: [
      Route({
        path: 'about',
        component: () => <About />
      })
    ]
  })
});

export default function App() {
  return <RouterProvider router={router} />;
}

Ключевые моменты:

  • Route может содержать дочерние маршруты через children.
  • Компоненты маршрутов передаются в component.
  • Основной роутер создается через createRouter, который передается в RouterProvider.

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

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

const router = createRouter({
  routeTree: Route({
    path: '/users/:userId',
    component: ({ params }) => <UserProfile userId={params.userId} />
  })
});
  • :userId — динамический сегмент.
  • Доступ к параметрам осуществляется через объект params.

Ленивая загрузка компонентов

Для оптимизации загрузки больших приложений рекомендуется использовать ленивую загрузку компонентов с React.lazy:

import { Route, createRouter, RouterProvider } from '@tanstack/router';
import { Suspense, lazy } from 'react';

const Home = lazy(() => import('./pages/Home'));
const About = lazy(() => import('./pages/About'));

const router = createRouter({
  routeTree: Route({
    path: '/',
    component: () => (
      <Suspense fallback={<div>Загрузка...</div>}>
        <Home />
      </Suspense>
    ),
    children: [
      Route({
        path: 'about',
        component: () => (
          <Suspense fallback={<div>Загрузка...</div>}>
            <About />
          </Suspense>
        )
      })
    ]
  })
});

Навигация между маршрутами

Для программной навигации используется хук useNavigate:

import { useNavigate } from '@tanstack/router';

function Header() {
  const navigate = useNavigate();
  
  return (
    <nav>
      <button onCl ick={() => navigate('/')}>Главная</button>
      <button onCl ick={() => navigate('/about')}>О нас</button>
    </nav>
  );
}
  • navigate(path) изменяет текущий маршрут.
  • Поддерживается переход с параметрами и query-параметрами.

Работа с query-параметрами

TanStack Router интегрирует управление query-параметрами через объект search:

const router = createRouter({
  routeTree: Route({
    path: '/products',
    component: ({ search }) => {
      const category = search.category || 'all';
      return <Products category={category} />;
    }
  })
});
  • Параметры доступны через search.
  • Можно использовать для фильтрации и пагинации.

Интеграция с Vite HMR

TanStack Router полностью совместим с Hot Module Replacement (HMR) Vite. При изменении кода маршруты автоматически обновляются без перезагрузки страницы. Для корректной работы нужно использовать RouterProvider на верхнем уровне приложения, чтобы весь роутер обновлялся при HMR:

import { createRoot } from 'react-dom/client';
import App from './App';

const root = createRoot(document.getElementById('root'));
root.render(<App />);

Организация маршрутов в Vite

В крупных проектах рекомендуется структурировать маршруты в отдельной папке, например src/routes, и экспортировать их через индексный файл:

src/
 └─ routes/
    ├─ index.js
    ├─ Home.js
    ├─ About.js
    └─ Users.js

index.js может выглядеть так:

import Home from './Home';
import About from './About';
import Users from './Users';
import { Route } from '@tanstack/router';

export const routeTree = Route({
  path: '/',
  component: Home,
  children: [
    Route({ path: 'about', component: About }),
    Route({ path: 'users/:userId', component: Users })
  ]
});

Затем роутер подключается в App.js:

import { createRouter, RouterProvider } from '@tanstack/router';
import { routeTree } from './routes';

const router = createRouter({ routeTree });

export default function App() {
  return <RouterProvider router={router} />;
}

Использование с TypeScript

TanStack Router полностью поддерживает TypeScript, позволяя типизировать параметры маршрутов и query-параметры:

type UserParams = {
  userId: string;
};

const userRoute = Route<{ params: UserParams }>({
  path: '/users/:userId',
  component: ({ params }) => {
    const { userId } = params;
    return <UserProfile userId={userId} />;
  }
});
  • Типизация повышает безопасность кода.
  • Ошибки при доступе к параметрам маршрутов обнаруживаются на этапе компиляции.

Заключение по организации в Vite

TanStack Router совместим с быстрым стартом Vite, поддерживает динамические маршруты, lazy loading и полноценную типизацию. Правильная структура файлов и использование хуков useNavigate, search и params обеспечивает чистую архитектуру маршрутизации и простоту масштабирования приложения.

Оглавление