tanstack-router은(는) 무엇을 하나요?
React 및 Solid 애플리케이션을 위한 타입-세이프 라우팅으로, 최고 수준의 검색 파라미터, 데이터 로딩, 그리고 React 생태계와의 원활한 통합을 제공합니다.
주요 기능
타입-세이프 라우팅
- 경로 및 검색 파라미터에 대한 완전한 타입 추론(Type Inference) 지원
- 컴파일 시점에 라우트 불일치 감지
- IDE 자동 완성 및 오류 검사
검색 파라미터(Search Params)
- 최고 수준의(first-class) 검색 파라미터 지원
- 타입-세이프한 검색 파라미터 정의 및 사용
- 자동 직렬화/역직렬화
- 검색 파라미터 유효성 검사(Zod, Yup 등과 통합)
데이터 로딩
- 라우트 수준의 데이터 로딩(Loader) 지원
- TanStack Query와의 원활한 통합
- 선언적 데이터 패칭 및 캐싱
- 로딩 상태 및 오류 처리
생태계 통합
- React 18+ 및 Solid.js 지원
- TanStack Query, TanStack Form, TanStack Table과 통합
- React Suspense 및 Error Boundaries 지원
- Vite, Next.js, Remix와 호환 가능
설치
npm install @tanstack/react-router
# 또는
npm install @tanstack/solid-router
기본 사용법
타입-세이프 라우트 정의
import { createRouter, createRoute } from '@tanstack/react-router'
// 루트 라우트 정의
const rootRoute = createRootRoute()
// 인덱스 라우트
const indexRoute = createRoute({
getParentRoute: () => rootRoute,
path: '/',
component: Index,
})
// 검색 파라미터가 있는 라우트
const searchRoute = createRoute({
getParentRoute: () => rootRoute,
path: '/search',
validateSearch: (search: Record<string, unknown>) => ({
query: search.query as string,
page: Number(search.page) || 1,
}),
component: SearchPage,
})
// 라우터 인스턴스 생성
const router = createRouter({
routeTree: rootRoute.addChildren([indexRoute, searchRoute]),
})
검색 파라미터 사용
import { useSearch, useNavigate } from '@tanstack/react-router'
function SearchPage() {
const search = useSearch({ from: searchRoute.id })
const navigate = useNavigate()
return (
<div>
<input
value={search.query}
onChange={(e) =>
navigate({
to: searchRoute,
search: { query: e.target.value, page: 1 },
})
}
/>
<p>페이지: {search.page}</p>
</div>
)
}
데이터 로딩
const userRoute = createRoute({
getParentRoute: () => rootRoute,
path: '/users/$userId',
loader: async ({ params: { userId } }) => {
const response = await fetch(`/api/users/${userId}`)
return response.json()
},
component: UserProfile,
})
function UserProfile() {
const data = useLoaderData({ from: userRoute.id })
return <div>{data.name}</div>
}
고급 기능
코드 생성(Code Generation)
npx @tanstack/react-router-codegen
파일 기반 라우팅(File-based Routing)
// src/routes/index.tsx
export const Route = createFileRoute('/')()
// src/routes/users/$userId.tsx
export const Route = createFileRoute('/users/$userId')()
지원 환경
- 프레임워크: React 18+, Solid.js
- 번들러: Vite, Webpack, esbuild
- 타입스크립트: 4.7+
- 도구: Cursor, Codex, Claude Code, GitHub Copilot
참고 자료
라이선스
MIT