TanStack Router یک روتر تایپ‌سیف، قدرتمند، بدون نیاز به فایل‌سیستم برای React است.
ویژگی‌های مهمش:

  • Type‑safe به صورت کامل (برای پروژه‌های TypeScript عالی است)
  • Data‑loading داخلی (شبیه React Router v7)
  • Caching و Preloading توکار
  • قابل ترکیب و انعطاف‌پذیر
  • مبتنی بر route tree به جای فایل‌ها

نصب

npm install @tanstack/react-router

مثال پایه (Simple Setup)

1) ساخت Router

// main.tsx یا index.tsx
import { RouterProvider } from '@tanstack/react-router'
import { router } from './router'

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

export default App

2) تعریف Route ها

// router.ts
import {
  RootRoute,
  Route,
  Router
} from '@tanstack/react-router'

// 1) Root route
const rootRoute = new RootRoute({
  component: () => <div>
    <h1>My App</h1>
    <hr />
    <Outlet />
  </div>,
})

// 2) Home page
const homeRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/',
  component: () => <div>صفحه اصلی</div>,
})

// 3) About page
const aboutRoute = new Route({
  getParentRoute: () => rootRoute,
  path: 'about',
  component: () => <div>درباره ما</div>,
})

// اتصال آنها به هم
const routeTree = rootRoute.addChildren([
  homeRoute,
  aboutRoute
])

export const router = new Router({ routeTree })

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

لینک دادن بین صفحات

TanStack Router از یک کامپوننت <Link /> مخصوص استفاده می‌کند.

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

<Link to="/">خانه</Link>
<Link to="/about">درباره ما</Link>

افزودن Route با پارامتر (Dynamic Route)

مثال: /users/:userId

const userRoute = new Route({
  getParentRoute: () => rootRoute,
  path: 'users/$userId',
  component: ({ params }) => (
    <div>
      User ID: {params.userId}
    </div>
  ),
})

لینک دادن:

<Link to="/users/$userId" params={{ userId: 42 }}>
  کاربر 42
</Link>

بارگذاری داده‌ها (Data Loader)

یکی از بهترین ویژگی‌های TanStack Router.

const postsRoute = new Route({
  getParentRoute: () => rootRoute,
  path: 'posts',
  loader: async () => {
    const res = await fetch('/api/posts')
    return res.json()
  },
  component: () => {
    const posts = postsRoute.useLoaderData()
    return (
      <div>
        {posts.map(p => (
          <div key={p.id}>{p.title}</div>
        ))}
      </div>
    )
  },
})

ویژگی‌های Loader:

  • قبل از رندر شدن صفحه اجرا می‌شود
  • داده را کش می‌کند
  • در صورت نیاز بازبارگذاری می‌کند

ساخت Layout با Route های پدر/فرزند

const dashboardRoute = new Route({
  getParentRoute: () => rootRoute,
  path: 'dashboard',
  component: () => (
    <div>
      <h2>داشبورد</h2>
      <Outlet />
    </div>
  ),
})

const dashboardHomeRoute = new Route({
  getParentRoute: () => dashboardRoute,
  path: '/',
  component: () => <div>صفحه اول داشبورد</div>,
})

const dashboardSettingsRoute = new Route({
  getParentRoute: () => dashboardRoute,
  path: 'settings',
  component: () => <div>تنظیمات</div>,
})

استفاده از Search Params (Query Params)

تعریف:

const searchRoute = new Route({
  getParentRoute: () => rootRoute,
  path: 'search',
  validateSearch: (search) => {
    return { q: String(search.q || '') }
  },
  component: () => {
    const { q } = searchRoute.useSearch()
    return <div>نتیجه جستجو: {q}</div>
  },
})

لینک دادن با search:

<Link to="/search" search={{ q: "react" }}>
  جستجوی React
</Link>

ویژگی‌های مهم دیگر TanStack Router (خلاصه)

  • Code Splitting عالی
  • Preloading مسیرها هنگام hover
  • Error Boundary داخلی
  • Redirect ساده
  • Navigation API قوی:
  const navigate = useNavigate()
  navigate({ to: "/about" })