TanStack Router v1 완벽 가이드 — 완전 타입 안전 React 라우터

TanStack Router 완전한 타입 추론

TanStack Router의 가장 강력한 차별점은 경로, 파라미터, 검색 파라미터, 라우터 컨텍스트 등 모든 라우팅 정보가 TypeScript로 완전히 추론된다는 점이다. useParams() 호출 시 반환 타입이 현재 라우트의 파라미터 타입으로 정확히 추론되며, 잘못된 파라미터 이름을 사용하면 컴파일 타임에 오류가 발생한다. Link 컴포넌트의 to prop도 실제 정의된 경로로 타입이 제한되어 존재하지 않는 경로로의 링크를 작성하면 빌드가 실패한다. React Router에서는 불가능한 수준의 타입 안전성이다.

// routes/posts.$postId.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/posts/$postId')({
  loader: ({ params }) => fetchPost(params.postId), // postId: string 자동 추론
  component: PostPage,
})

function PostPage() {
  const { postId } = Route.useParams()  // 타입: { postId: string }
  const post = Route.useLoaderData()    // 로더 반환 타입 자동 추론
  return <article>{post.title}</article>
}

TanStack Router 검색 파라미터 스키마 검증

URL 검색 파라미터는 항상 문자열이지만, TanStack Router에서는 라우트 정의 시 validateSearch 함수를 선언하여 파싱과 직렬화를 자동 처리할 수 있다. Zod나 Valibot과 통합하면 검색 파라미터의 타입 변환과 유효성 검사를 라우터 레벨에서 처리한다. ?page=2&sort=asc처럼 URL에 저장된 UI 상태가 타입 안전하게 컴포넌트에 전달되어 parseInt, toString 변환 코드가 사라진다. 잘못된 검색 파라미터 값이 들어오면 라우터가 자동으로 기본값으로 폴백할 수 있다.

TanStack Router 파일 명명 규칙과 자동 타입 생성

TanStack Router의 파일 기반 라우팅에서는 파일 이름 규칙으로 라우트 트리가 자동 생성된다. routes/posts.$postId.tsx가 /posts/:postId 라우트가 되며, 동적 세그먼트는 $ 접두사로 표현된다. Vite 플러그인이나 TanStack Router CLI를 사용하면 파일을 생성할 때마다 routeTree.gen.ts 타입 정의 파일이 자동 업데이트되어, 전체 라우터의 타입 정보가 항상 최신 상태를 유지한다. 이 파일은 Git에 커밋하여 팀 전체가 동일한 라우터 타입 정보를 공유한다.

TanStack Router 중첩 레이아웃과 병렬 데이터 로딩

라우트별 loader 함수를 선언하면 컴포넌트가 렌더링되기 전에 데이터를 병렬로 로드한다. 중첩 라우트의 부모와 자식 로더가 동시에 실행되어 데이터 워터폴을 방지한다. 로더에서 반환한 데이터는 Route.useLoaderData()로 타입 안전하게 접근할 수 있으며, 로딩 중에는 라우트별 pendingComponent가 표시된다. 이 패턴은 React Router v6의 loader와 유사하지만 타입 추론이 훨씬 정밀하다.

TanStack Router 핵심 API 매핑

React Router의 useParams, useNavigate, useSearchParams는 TanStack Router의 useParams, useNavigate, useSearch에 각각 대응된다. 주요 차이는 반환 타입의 정밀도로, TanStack Router에서는 실제 라우트 스키마로 타입이 추론된다. Navigate 컴포넌트와 redirect() 함수도 제공되어 프로그래밍 방식의 내비게이션을 지원한다. 라우트 단위로 점진적 마이그레이션이 가능하여 대형 프로젝트에서도 위험 부담 없이 전환할 수 있다.

TanStack Router DevTools와 디버깅

TanStack Router DevTools는 현재 라우터 상태, 로더 실행 현황, 캐시 상태를 시각적으로 확인할 수 있는 도구를 제공한다. 개발 모드에서 화면 하단에 DevTools 패널을 추가하면 라우터 동작을 실시간으로 모니터링할 수 있다. TanStack Query와 함께 사용하는 경우 Query DevTools도 함께 활성화하면 데이터 페칭과 캐싱 상태를 통합적으로 확인할 수 있다.