본문으로 바로가기
검색 (Ctrl+K)

TanStack Router vs React Router, 알고 써 보자

·7분 읽기·
---
·
개발

라우터가 왤케 많냐

배경

React로 SPA를 만들 때 라우터는 React Router를 써 왔다. 그러다 TanStack Router가 React Router와 무엇이 다른지, 둘 다 loader가 있는데 캐싱은 어떻게 다른지 궁금해져서 정리했다.

TanStack Router란 무엇인가

TanStack Router (새 탭에서 열림)는 TanStack Query를 만든 팀이 낸 React용 라우터다. 경로, 경로 파라미터, 쿼리스트링, loader가 돌려주는 데이터까지 전부 TypeScript 타입으로 추론해 준다.

라우트는 파일로 정의한다. src/routes/products.tsx 파일이 /products 경로가 된다.

typescript
// src/routes/products.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/products')({
  component: Products,
})

function Products() {
  return <h1>상품 목록</h1>
}

createFileRoute에 경로를 넘기고, 그 경로에서 렌더링할 컴포넌트를 component로 지정한다. Vite 플러그인이 routes 폴더를 읽어 routeTree.gen.ts를 생성하고, 라우터는 이 파일에서 경로와 파라미터 타입을 추론한다.

왜 쓰는걸까?

React Router에서 페이지를 이동할 때는 보통 이렇게 쓴다.

typescript
navigate(`/orders/${orderId}?tab=${tab}&page=${page}`)

컴파일러는 이 줄에서 다음을 확인하지 않는다.

  • /orders/:orderId라는 라우트가 실제로 있는지
  • tab에 넣은 값이 그 화면이 아는 탭 이름인지
  • page가 숫자인지

경로 이름을 바꾸거나 탭 하나를 없애도 이 줄은 그대로 컴파일된다. 런타임에 없는 경로로 이동하거나, 화면이 모르는 tab 값을 그대로 받는다.

받는 쪽도 같다. useSearchParams()로 꺼낸 값은 전부 string | null이어서, 숫자로 바꾸고 기본값을 채우는 코드를 화면마다 다시 쓴다.

TanStack Router에서는 없는 경로, 빠진 파라미터, 스키마에 없는 쿼리 값이 타입 에러로 잡힌다.

주요 기능

쿼리스트링을 스키마로 검증하고 타입이 있는 객체로 읽는다

라우트의 validateSearch에 쿼리스트링의 스키마를 넘긴다.

typescript
import { z } from 'zod'

const searchSchema = z.object({
  page: z.number().catch(1),
  sort: z.enum(['name', 'price']).catch('name'),
})

export const Route = createFileRoute('/products')({
  validateSearch: searchSchema,
  component: Products,
})

/products?page=2&sort=price로 들어오면 라우터가 쿼리스트링을 이 스키마로 검증한다. ?page=abc처럼 잘못된 값이 들어오면 catch(1)이 기본값 1로 바꾼다.

typescript
function Products() {
  const { page, sort } = Route.useSearch()
  // page: number
  // sort: 'name' | 'price'
}

컴포넌트에서는 Route.useSearch()로 읽는다. 반환값의 타입은 스키마에서 나오므로 page는 number, sort는 'name' | 'price'다.

typescript
<Link to="/products" search={(prev) => ({ ...prev, page: prev.page + 1 })}>
  다음
</Link>

값을 바꿀 때는 Link의 search에 함수를 넘긴다. 이전 값을 받아 새 객체를 반환하는 함수다. sort: 'cheap'처럼 스키마에 없는 값을 넣으면 타입 에러가 난다.

Link의 to와 params를 컴파일 시점에 검사한다

typescript
<Link to="/orders/$orderId" params={{ orderId: order.id }}>
  주문 상세
</Link>

to에는 실제로 있는 경로만 쓸 수 있다. to="/order/$orderId"처럼 오타를 내거나 params를 빼먹으면 타입 에러가 난다.

링크에 hover하면 코드와 데이터를 preload한다

typescript
const router = createRouter({
  routeTree,
  defaultPreload: 'intent',
})

createRouter의 defaultPreload를 'intent'로 두면, 링크에 hover하거나 터치를 시작할 때 그 라우트의 JS 청크를 받고 loader를 실행한다. 클릭했을 때는 코드와 데이터가 이미 준비돼 있다.

React Router와 코드 비교

상품 목록 화면을 두 라우터로 짜서 비교한다. 페이지 번호와 정렬 기준을 URL에 두고(/products?page=2&sort=price), 상품을 누르면 상세 페이지로 간다. React Router는 v7 프레임워크 모드 기준이다.

쿼리스트링 읽기

typescript
// React Router
export async function loader({ request }: Route.LoaderArgs) {
  const params = new URL(request.url).searchParams
  const page = Number(params.get('page')) || 1
  const sort = params.get('sort') === 'price' ? 'price' : 'name'
  return { products: await fetchProducts({ page, sort }), page }
}

React Router에서는 request.url에서 searchParams를 꺼낸다. params.get()의 반환값은 string | null이라서 숫자 변환, 기본값, 허용된 값인지 확인하는 코드를 직접 쓴다.

typescript
// TanStack Router
export const Route = createFileRoute('/products')({
  validateSearch: searchSchema,
  loaderDeps: ({ search }) => search,
  loader: ({ deps }) => fetchProducts(deps),
  component: Products,
})

TanStack Router에서는 validateSearch에 넘긴 스키마가 파싱과 검증을 한다. loader는 검증이 끝난 { page: number; sort: 'name' | 'price' }를 deps로 받는다.

쿼리스트링 바꾸기

typescript
// React Router
const [searchParams] = useSearchParams()

const withParam = (key: string, value: string) => {
  const next = new URLSearchParams(searchParams)
  next.set(key, value)
  return `?${next}`
}

<Link to={withParam('sort', 'price')}>가격순</Link>

React Router에서는 쿼리스트링 하나만 바꾼 URL을 만들려면 withParam 같은 헬퍼를 직접 짠다. 키와 값이 모두 문자열이라 withParam('srot', 'price')라고 써도 타입 검사를 통과한다.

typescript
// TanStack Router
<Link to="/products" search={(prev) => ({ ...prev, sort: 'price' })}>
  가격순
</Link>

TanStack Router에서는 search에 객체를 반환하는 함수를 넘긴다. srot처럼 스키마에 없는 키를 쓰면 타입 에러가 난다.

상세 페이지 링크

typescript
// React Router
<Link to={`/products/${p.id}`}>{p.name}</Link>

// TanStack Router
<Link to="/products/$productId" params={{ productId: p.id }}>{p.name}</Link>

React Router의 to는 문자열이다. 상세 경로를 /items/:id로 바꿔도 이 링크는 컴파일 에러 없이 남아 있다가, 눌렀을 때 없는 경로로 이동한다. TanStack Router에서는 경로를 바꾸는 즉시 이 Link에 타입 에러가 난다.

React Router v7도 프레임워크 모드에서는 ./+types/products가 생성돼 loaderData의 타입이 추론된다. 하지만 Link의 to와 쿼리스트링은 어느 모드에서든 문자열이다.

loader란 무엇인가

loader는 컴포넌트가 렌더링되기 전에 데이터를 가져오는 함수다. 두 라우터 모두 제공한다. 컴포넌트가 마운트된 뒤 useEffect로 요청을 시작하는 방식과 달리, 페이지 이동이 시작되는 시점에 요청을 보낸다.

loader 실행 과정

TanStack Router의 loader는 다음 순서로 실행된다.

사용자가 링크를 클릭 → URL과 일치하는 route 매칭 → validateSearch로 쿼리스트링 검증 → loaderDeps로 loader에 넘길 값 계산 → loader 실행 (중첩 라우트의 loader는 병렬 실행) → loader가 끝나면 컴포넌트 렌더링 → 컴포넌트에서 Route.useLoaderData()로 데이터 접근

사용 예시

typescript
export const Route = createFileRoute('/products/$productId')({
  loader: ({ params }) => fetchProduct(params.productId),
  component: ProductDetail,
})

loader는 경로 파라미터를 params로 받는다. /products/$productId 경로이므로 params.productId의 타입은 string으로 추론된다.

typescript
function ProductDetail() {
  const product = Route.useLoaderData()
  return <h1>{product.name}</h1>
}

컴포넌트에서는 Route.useLoaderData()로 loader가 반환한 값을 읽는다. 타입은 fetchProduct의 반환 타입 그대로다. React Router의 useLoaderData() as Product처럼 타입을 단언할 필요가 없다.

typescript
export const Route = createFileRoute('/products')({
  validateSearch: searchSchema,
  loaderDeps: ({ search }) => ({ page: search.page, sort: search.sort }),
  loader: ({ deps }) => fetchProducts(deps),
})

loader가 쿼리스트링을 써야 하면 loaderDeps를 거친다. loader는 쿼리스트링을 직접 읽지 못하고, loaderDeps가 반환한 값만 deps로 받는다.

두 라우터의 loader 차이: 캐시

목록 페이지에서 상세 페이지로 갔다가 뒤로 가기를 누르는 경우를 보자.

React Router는 loader 데이터를 캐시하지 않는다. 현재 URL에 매칭된 라우트의 loader 데이터만 유지하므로, 목록으로 돌아오면 loader를 다시 실행하고 응답을 기다린다. 캐시가 필요하면 Cache-Control 헤더로 브라우저나 CDN 캐시를 쓴다.

TanStack Router는 loader 결과를 메모리에 캐시한다. 목록으로 돌아오면 캐시된 데이터를 바로 보여 주고, 백그라운드에서 loader를 다시 실행해 응답이 오면 화면을 갱신한다. stale-while-revalidate 방식이다.

typescript
export const Route = createFileRoute('/products')({
  validateSearch: searchSchema,
  loaderDeps: ({ search }) => ({ page: search.page, sort: search.sort }),
  loader: ({ deps }) => fetchProducts(deps),
  staleTime: 10_000,
})

staleTime은 캐시된 데이터를 fresh로 보는 시간(ms)이다. 이 시간 안에는 loader를 다시 실행하지 않는다. 기본값은 0이라서, 설정하지 않으면 라우트에 들어올 때마다 백그라운드에서 loader를 다시 실행한다.

캐시 키는 라우트 경로, 경로 파라미터, loaderDeps가 반환한 값이다. 그래서 page=1의 결과와 page=2의 결과가 따로 저장된다. 쿼리스트링을 loaderDeps로 넘기게 한 이유가 여기에 있다.

loader와 TanStack Query를 함께 써야 하는 이유

TanStack Router의 캐시만으로는 안 되는 것이 두 가지 있다.

  • 캐시 키가 라우트에 묶여 있어서, /products의 loader가 가져온 상품 목록을 /dashboard에서 읽을 수 없다.
  • 상품을 수정한 뒤 그 상품과 관련된 데이터만 다시 가져올 수 없다. router.invalidate()로 화면에 있는 loader를 전부 다시 실행해야 한다.

반대로 TanStack Query만 쓰면 컴포넌트가 마운트된 뒤에야 요청이 시작된다.

둘을 함께 쓰면 loader가 페이지 이동 시점에 요청을 시작하고, 데이터는 TanStack Query 캐시에 저장된다. 여러 라우트가 같은 쿼리 키로 데이터를 공유하고, 수정 후에는 invalidateQueries로 관련 쿼리만 다시 가져온다.

함께 사용하는 예시

상품 상세 페이지(/products/$productId)를 예로 든다.

typescript
const queryClient = new QueryClient()

const router = createRouter({
  routeTree,
  context: { queryClient },
  defaultPreloadStaleTime: 0,
})

loader는 훅이 아니라서 useQueryClient를 쓸 수 없다. 그래서 createRouter의 context에 queryClient를 넣어 loader에 전달한다.

defaultPreloadStaleTime: 0은 라우터가 preload한 데이터를 항상 stale로 취급하게 한다. 라우터와 Query가 각각 staleTime을 갖지 않도록, 다시 가져올지는 Query의 staleTime만으로 판단하게 하는 설정이다.

typescript
const productQueryOptions = (id: string) =>
  queryOptions({
    queryKey: ['products', id],
    queryFn: () => fetchProduct(id),
    staleTime: 30_000,
  })

쿼리 키와 쿼리 함수를 queryOptions로 한곳에 정의한다. loader와 컴포넌트가 같은 옵션을 쓰기 위해서다.

typescript
export const Route = createFileRoute('/products/$productId')({
  loader: ({ context: { queryClient }, params }) =>
    queryClient.ensureQueryData(productQueryOptions(params.productId)),
  component: ProductDetail,
})

loader에서 queryClient.ensureQueryData를 호출한다. ensureQueryData는 캐시에 데이터가 있으면 그 데이터를 반환하고, 없으면 queryFn을 실행해 캐시에 저장한다.

typescript
function ProductDetail() {
  const { productId } = Route.useParams()
  const { data: product } = useSuspenseQuery(productQueryOptions(productId))

  return <h1>{product.name}</h1>
}

컴포넌트에서는 useLoaderData 대신 useSuspenseQuery로 읽는다. loader가 캐시를 채워 뒀으므로 로딩 상태 없이 바로 렌더링된다. 이후 다른 곳에서 invalidateQueries({ queryKey: ['products', productId] })를 호출하면 이 컴포넌트도 새 데이터로 갱신된다.

라우터는 loader를 실행할 시점(진입, preload)만 정하고, staleTime, gcTime, invalidation은 Query가 관리한다.

느린 데이터는 기다리지 않기

typescript
loader: async ({ context: { queryClient }, params }) => {
  queryClient.prefetchQuery(reviewsQueryOptions(params.productId))
  await queryClient.ensureQueryData(productQueryOptions(params.productId))
},

상품 정보는 await로 기다리고, 리뷰는 prefetchQuery로 요청만 보낸다. 리뷰 목록 컴포넌트를 <Suspense>로 감싸 두면 상품 정보가 먼저 뜨고, 리뷰는 응답이 올 때까지 fallback이 보이다가 목록으로 바뀐다.

TanStack Router를 사용하기 좋은 경우

  • Vite 기반 SPA를 새로 시작할 때
  • 필터, 정렬, 페이지 번호 같은 상태를 쿼리스트링에 둘 때
  • TanStack Query를 이미 쓰고 있을 때
  • 라우트가 많아서 경로를 바꿀 때 깨지는 링크를 컴파일 시점에 찾고 싶을 때

React Router가 더 맞는 경우도 있다. React Router에는 action과 <Form>이 있어서 폼 제출과 그 뒤의 재검증을 라우터가 처리한다. TanStack Router에는 이 기능이 없어서 useMutation을 쓴다. 폼 제출이 중심인 서버 렌더링 앱이라면 React Router가 낫다.

정리

TanStack RouterReact Router v7
경로와 Link라우트 트리에서 타입 추론. 없는 경로는 컴파일 에러문자열
쿼리스트링스키마로 검증한 객체URLSearchParams를 직접 파싱
loader 데이터 타입추론됨프레임워크 모드에서 추론됨
loader 캐시내장. staleTime으로 조절없음. 라우트에 진입할 때마다 loader 실행
preloaddefaultPreload: 'intent'프레임워크 모드의 prefetch="intent"
데이터 수정없음. TanStack Query의 mutationaction과 <Form>

결론

두 라우터가 갈리는 곳은 쿼리스트링과 캐시다. TanStack Router는 쿼리스트링을 스키마로 검증된 객체로 다루고, loader 결과를 캐시한다. React Router는 쿼리스트링을 직접 파싱하고, loader를 매번 다시 실행한다.

쿼리스트링에 상태를 많이 두는 SPA를 새로 시작한다면 TanStack Router를 고르겠다. TanStack Query를 함께 쓰면 loader는 요청을 시작하는 시점만 맡고 캐시는 Query가 관리한다.

참고 자료