TanStack Router 완벽 가이드: React Router 대체제의 모든 것

안녕하세요! 오늘은 React 개발자들 사이에서 핫한 라우팅 라이브러리, TanStack Router(이전 React Location)에 대해 상세히 알아보겠습니다. React Router를 대체할 수 있는 이 현대적인 라우터는 어떤 특징과 장점이 있는지, 실제 프로젝트에 어떻게 적용할 수 있는지 함께 살펴봅시다!

목차

1. TanStack Router란?
2. React Router와 TanStack Router 비교
3. TanStack Router 설치 및 기본 설정
4. TanStack Router 핵심 기능
5. 실전 코드 예제
6. 성능 최적화 팁
7. TanStack Router 마이그레이션 가이드
8. 자주 묻는 질문(FAQ)

TanStack Router란?

TanStack Router는 Tanner Linsley가 개발한 타입스크립트 기반의 현대적인 라우팅 라이브러리입니다. 이전에는 React Location으로 알려졌으며, TanStack 제품군(React Query, React Table 등)의 일부로 리브랜딩되었습니다.

"TanStack Router는 타입 안전성, 자동화된 로딩/에러 상태, 그리고 직관적인 API를 중점으로 설계된 차세대 라우팅 솔루션입니다."

주요 특징

• 완벽한 타입 안전성: TypeScript로 작성되어 타입 오류를 개발 단계에서 잡아냅니다.
• 자동화된 데이터 로딩: 경로 로더를 통한 효율적인 데이터 페칭 방식 제공
• 내장된 상태 관리: 로딩, 에러, 데이터 상태를 자동으로 관리
• 중첩 라우팅과 병렬 라우팅: 복잡한 UI 구조 쉽게 구현 가능
• 코드 분할 내장: 자동 지연 로딩으로 초기 번들 크기 감소
• 탐색 API: 풍부한 프로그래밍 방식 탐색 지원
• 리액트 서스펜스 지원: 최신 리액트 기능과 완벽 호환

React Router와 TanStack Router 비교

가장 많이 사용되는 React Router와 TanStack Router를 비교해보겠습니다:

기능React Router (v6)TanStack Router

타입 안전성	부분적 지원	완벽한 엔드투엔드 타입 안전성
데이터 로딩	loader API (v6.4+)	내장 로더 시스템
코드 분할	수동 구성 필요	자동 지원
중첩 라우팅	지원	개선된 중첩 및 병렬 라우팅
사이즈	~8-9KB (gzipped)	~5KB (gzipped)
개발 패턴	JSX 기반	객체 구성 API
학습 곡선	완만함	중간 (새로운 패러다임)
커뮤니티/생태계	매우 큼	성장 중

TanStack Router 설치 및 기본 설정

TanStack Router를 시작하는 방법은 간단합니다:

bash

 

# npm으로 설치
npm install @tanstack/react-router

# yarn으로 설치
yarn add @tanstack/react-router

기본 설정 코드

tsx

 

// 라우트 정의 (routes.tsx)
import { RootRoute, Route, Router } from '@tanstack/react-router'
import { Home } from './pages/Home'
import { About } from './pages/About'
import { RootLayout } from './layouts/RootLayout'

// 루트 라우트 생성
const rootRoute = new RootRoute({
  component: RootLayout,
})

// 자식 라우트 정의
const homeRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/',
  component: Home,
})

const aboutRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/about',
  component: About,
})

// 라우터 객체 생성
const routeTree = rootRoute.addChildren([homeRoute, aboutRoute])
const router = new Router({ routeTree })

// 타입 선언
declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

export default router

그리고 앱의 진입점에서:

tsx

 

// main.tsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import { RouterProvider } from '@tanstack/react-router'
import router from './routes'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <RouterProvider router={router} />
  </React.StrictMode>,
)

TanStack Router 핵심 기능

1. 타입 안전한 라우트 정의

TanStack Router의 가장 큰 장점 중 하나는 타입스크립트와의 완벽한 통합입니다:

tsx

 

// 경로 파라미터를 포함한 타입 안전 라우트
const userRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/users/$userId',
  // 타입 안전한 파라미터 정의
  parseParams: (params) => ({
    userId: z.string().parse(params.userId),
  }),
  component: UserProfile,
})

2. 데이터 로딩과 캐싱

TanStack Router는 각 라우트에 데이터 로더를 쉽게 연결할 수 있습니다:

tsx

 

const productsRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/products',
  // 데이터 로더 정의
  loader: async () => {
    const response = await fetch('https://api.example.com/products')
    return response.json()
  },
  component: Products,
})

컴포넌트에서 데이터 사용:

tsx

 

function Products() {
  // 로더에서 로드된 데이터 접근
  const productsData = productsRoute.useLoaderData()
  
  return (
    <div>
      <h1>제품 목록</h1>
      {productsData.map(product => (
        <ProductCard key={product.id} product={product} />
      ))}
    </div>
  )
}

3. 중첩 라우팅

복잡한 UI 구조를 위한 중첩 라우팅 예제:

tsx

 

// 대시보드 레이아웃
const dashboardRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/dashboard',
  component: DashboardLayout,
})

// 대시보드 내 중첩 라우트들
const dashboardHomeRoute = new Route({
  getParentRoute: () => dashboardRoute,
  path: '/',
  component: DashboardHome,
})

const dashboardProfileRoute = new Route({
  getParentRoute: () => dashboardRoute,
  path: '/profile',
  component: DashboardProfile,
})

// 라우트 트리에 추가
rootRoute.addChildren([
  dashboardRoute.addChildren([
    dashboardHomeRoute,
    dashboardProfileRoute,
  ])
])

4. 링크 및 네비게이션

타입 안전한 링크 생성 및 프로그래밍 방식의 네비게이션:

tsx

 

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

function Navigation() {
  // 프로그래밍 방식 네비게이션
  const navigate = useNavigate()
  
  return (
    <nav>
      {/* 타입 안전한 링크 컴포넌트 */}
      <Link to="/" activeProps={{ className: 'active' }}>
        홈
      </Link>
      <Link to="/about" activeProps={{ className: 'active' }}>
        소개
      </Link>
      
      {/* 사용자 ID를 동적으로 포함한 링크 */}
      <Link to="/users/$userId" params={{ userId: '123' }}>
        사용자 프로필
      </Link>
      
      {/* 프로그래밍 방식 네비게이션 */}
      <button onClick={() => navigate({ to: '/dashboard' })}>
        대시보드로 이동
      </button>
    </nav>
  )
}

실전 코드 예제

1. 인증 기능이 포함된 라우터 설정

tsx

 

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

// 루트 레이아웃
const rootRoute = new RootRoute({
  component: RootLayout,
})

// 공개 라우트
const publicRoutes = [
  new Route({
    getParentRoute: () => rootRoute,
    path: '/',
    component: Home,
  }),
  new Route({
    getParentRoute: () => rootRoute,
    path: '/login',
    component: Login,
  }),
]

// 보호된 라우트 (인증 필요)
const protectedRoutes = [
  new Route({
    getParentRoute: () => rootRoute,
    path: '/dashboard',
    // 인증 검사 미들웨어
    beforeLoad: async () => {
      if (!isUserAuthenticated()) {
        throw redirect({
          to: '/login',
          search: {
            redirect: '/dashboard',
          }
        })
      }
    },
    component: Dashboard,
  }),
]

const routeTree = rootRoute.addChildren([...publicRoutes, ...protectedRoutes])
const router = new Router({ routeTree })

2. Search Params 활용 예제

tsx

 

// 검색 기능 구현
const searchRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/search',
  // 검색 파라미터 정의
  validateSearch: (search) => ({
    query: search.query || '',
    category: search.category || 'all',
    page: Number(search.page || 1),
  }),
  // 검색 데이터 로딩
  loader: async ({ search }) => {
    const { query, category, page } = search
    return fetchSearchResults(query, category, page)
  },
  component: SearchResults,
})

// 검색 컴포넌트
function SearchResults() {
  const { query, category, page } = searchRoute.useSearch()
  const results = searchRoute.useLoaderData()
  const navigate = useNavigate()
  
  function handleSearch(newQuery) {
    navigate({
      to: '/search',
      search: { query: newQuery, category, page: 1 },
      replace: true
    })
  }
  
  return (
    <div>
      <SearchForm onSearch={handleSearch} initialQuery={query} />
      <CategoryFilter 
        category={category} 
        onChange={(newCategory) => 
          navigate({
            to: '/search',
            search: { query, category: newCategory, page: 1 },
            replace: true
          })
        } 
      />
      <ResultsList results={results} />
      <Pagination 
        currentPage={page} 
        totalPages={results.totalPages}
        onPageChange={(newPage) => 
          navigate({
            to: '/search',
            search: { query, category, page: newPage },
            replace: true
          })
        }
      />
    </div>
  )
}

성능 최적화 팁

1. 자동 코드 분할 활용

TanStack Router는 자동 코드 분할을 지원합니다:

tsx

 

// 지연 로딩 컴포넌트 정의
const LazyAdminDashboard = lazy(() => import('./pages/AdminDashboard'))

const adminRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/admin',
  // React.lazy와 Suspense 활용
  component: () => (
    <Suspense fallback={<LoadingSpinner />}>
      <LazyAdminDashboard />
    </Suspense>
  ),
})

2. 데이터 프리페칭

사용자 경험 향상을 위한 데이터 프리페칭:

tsx

 

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

function ProductsList({ products }) {
  const router = useRouter()
  
  return (
    <ul>
      {products.map(product => (
        <li 
          key={product.id}
          onMouseEnter={() => {
            // 마우스 호버 시 데이터 미리 로드
            router.preloadRoute({
              to: `/products/$productId`,
              params: { productId: product.id }
            })
          }}
        >
          <Link 
            to="/products/$productId" 
            params={{ productId: product.id }}
          >
            {product.name}
          </Link>
        </li>
      ))}
    </ul>
  )
}

3. 메모이제이션 활용

TanStack Router의 성능을 최적화하기 위한 메모이제이션:

tsx

 

import { useMemo } from 'react'
import { useMatch } from '@tanstack/react-router'

function ProductFilters() {
  const { params } = useMatch('/products/$categoryId')
  
  // 필터 상태 메모이제이션
  const filters = useMemo(() => {
    return computeFiltersForCategory(params.categoryId)
  }, [params.categoryId])
  
  return <FilterPanel filters={filters} />
}

TanStack Router 마이그레이션 가이드

React Router에서 TanStack Router로 마이그레이션하는 과정은 단계적으로 진행할 수 있습니다:

1. 기본 구조 변경

React Router:

jsx

 

<Routes>
  <Route path="/" element={<Layout />}>
    <Route index element={<Home />} />
    <Route path="about" element={<About />} />
    <Route path="users/:userId" element={<UserProfile />} />
  </Route>
</Routes>

TanStack Router:

tsx

 

const rootRoute = new RootRoute({
  component: Layout,
})

const indexRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/',
  component: Home,
})

const aboutRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/about',
  component: About,
})

const userRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/users/$userId',
  component: UserProfile,
})

const routeTree = rootRoute.addChildren([
  indexRoute,
  aboutRoute,
  userRoute,
])

2. 데이터 로딩 변환

React Router (v6.4+):

jsx

 

const loader = async ({ params }) => {
  const response = await fetch(`/api/users/${params.userId}`)
  return response.json()
}

<Route path="users/:userId" element={<UserProfile />} loader={loader} />

// 컴포넌트에서
const data = useLoaderData()

TanStack Router:

tsx

 

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

// 컴포넌트에서
const data = userRoute.useLoaderData()

3. 파라미터 및 쿼리 파라미터 변환

React Router:

jsx

 

// 경로 파라미터
const { userId } = useParams()

// 쿼리 파라미터
const [searchParams, setSearchParams] = useSearchParams()
const query = searchParams.get('query')

TanStack Router:

tsx

 

// 경로 파라미터
const { params } = useMatch('/users/$userId')
const userId = params.userId

// 쿼리 파라미터 (검색 파라미터로 명명)
const { query } = searchRoute.useSearch()

자주 묻는 질문(FAQ)

TanStack Router는 Next.js나 Remix와 함께 사용할 수 있나요?

TanStack Router는 주로 클라이언트 사이드 라우팅을 위해 설계되었습니다. Next.js나 Remix와 같은 프레임워크는 자체 라우팅 시스템을 갖추고 있어 함께 사용하는 것은 권장되지 않습니다. 그러나 Next.js에서 클라이언트 측 라우팅만 필요한 특정 페이지나 섹션에서는 사용할 수 있습니다.

React Router와 비교해 TanStack Router의 주요 장점은 무엇인가요?

TanStack Router의 주요 장점은 다음과 같습니다:

• 완전한 타입 안전성 (TypeScript와의 통합)
• 내장된 데이터 로딩 시스템
• 자동화된 코드 분할
• 더 선언적이고 구조화된 라우트 정의 방식
• 더 작은 번들 크기
• React Query와의 원활한 통합

TanStack Router에서 중첩 레이아웃을 구현하는 방법은?

TanStack Router에서 중첩 레이아웃은 부모-자식 관계를 통해 구현됩니다:

tsx

 

// 부모 라우트 (레이아웃 포함)
const dashboardRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/dashboard',
  component: DashboardLayout, // 공통 레이아웃
})

// 자식 라우트들
const overviewRoute = new Route({
  getParentRoute: () => dashboardRoute, // 부모 라우트 참조
  path: '/',
  component: DashboardOverview,
})

const settingsRoute = new Route({
  getParentRoute: () => dashboardRoute, // 부모 라우트 참조
  path: '/settings',
  component: DashboardSettings,
})

// DashboardLayout 컴포넌트 내부에서 Outlet 사용
function DashboardLayout() {
  return (
    <div className="dashboard-layout">
      <DashboardSidebar />
      <div className="dashboard-content">
        {/* 자식 라우트 컴포넌트가 여기에 렌더링됨 */}
        <Outlet />
      </div>
    </div>
  )
}

TanStack Router에서 라우트 가드를 구현하는 방법은?

라우트 가드는 beforeLoad 훅을 사용하여 구현할 수 있습니다:

tsx

 

const protectedRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/protected',
  // 라우트 가드 역할을 하는 beforeLoad 훅
  beforeLoad: async () => {
    const isAuthenticated = await checkAuthStatus()
    if (!isAuthenticated) {
      // 인증되지 않은 사용자는 로그인 페이지로 리다이렉트
      throw redirect({
        to: '/login',
        search: {
          returnTo: '/protected'
        }
      })
    }
  },
  component: ProtectedContent,
})

TanStack Router와 React Query를 함께 사용하는 방법은?

TanStack Router는 React Query와 원활하게 통합됩니다:

tsx

 

import { useQuery } from '@tanstack/react-query'

const userRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/users/$userId',
  // React Query 키 미리 정의
  loader: ({ params }) => ({
    queryKey: ['user', params.userId],
    queryFn: () => fetchUser(params.userId),
  }),
  component: UserProfile,
})

function UserProfile() {
  // 라우트 파라미터 가져오기
  const { params } = useMatch('/users/$userId')
  
  // 로더에서 정의한 queryKey와 queryFn 사용
  const loaderData = userRoute.useLoaderData()
  
  // React Query 훅으로 데이터 가져오기
  const { data: user, isLoading, error } = useQuery(loaderData)
  
  if (isLoading) return <Loading />
  if (error) return <Error message={error.message} />
  
  return <UserDetails user={user} />
}

마치며

TanStack Router는 기존 React Router의 대안으로, 특히 TypeScript 프로젝트에서 타입 안정성과 성능 최적화를 중시하는 개발자들에게 매력적인 선택지입니다. 기본적인 라우팅뿐만 아니라 데이터 로딩, 코드 분할 등 모던 웹 애플리케이션에 필요한 다양한 기능을 통합적으로 제공합니다.

React Query, React Table 등 다른 TanStack 라이브러리와의 원활한 통합도 큰 장점입니다. 복잡한 엔터프라이즈급 애플리케이션이나 타입스크립트를 활용한 프로젝트를 계획 중이라면, TanStack Router를 도입해보는 것을 강력히 추천합니다!

새로운 프로젝트를 시작하거나 기존 프로젝트를 현대화하는 과정에서 TanStack Router는 확실히 고려해볼 만한 가치가 있는 라이브러리입니다. 개발 경험과 최종 사용자 경험 모두를 개선할 수 있는 강력한 도구임이 틀림없습니다.