TanStack Router 타입 세이프 경로 파라미터 정리

TanStack Router는 파일 이름의 $slug, $id 같은 세그먼트를 라우트 트리 생성 시점에 파싱해, useParams()나 <Link params={{ ... }}>를 쓸 때 파라미터 이름과 타입을 자동으로 추론해 줍니다. 예를 들어 src/routes/$locale/blog/$slug.tsx 파일이 있으면, 이 라우트로 향하는 모든 <Link to="/$locale/blog/$slug" params={{ locale, slug }}> 호출에서 locale과 slug를 빠뜨리거나 오타를 내는 즉시 타입 에러가 발생합니다.

기본적으로 경로 파라미터는 문자열이지만, 숫자 ID처럼 특정 형태를 강제하고 싶다면 라우트 정의에서 params.parse를 사용할 수 있습니다.

export const Route = createFileRoute('/$locale/posts/$postId')({
  params: {
    parse: (raw) => ({ postId: Number(raw.postId) }),
    stringify: (parsed) => ({ postId: String(parsed.postId) }),
  },
  loader: ({ params }) => fetchPost(params.postId), // params.postId: number
})

파일 경로가 곧 타입 선언이 된다는 것이, 라우터를 파일 기반으로 설계했을 때 얻는 가장 큰 이점이다.

이 프로젝트에서는 /$locale 레이아웃 라우트 아래에 모든 페이지가 중첩되어 있기 때문에, locale 파라미터가 모든 하위 라우트의 params에 자동으로 포함됩니다. isLocale() 가드로 런타임 값을 좁혀주는 것만으로 getBlogEntry(slug, locale)처럼 로케일이 필요한 함수에 안전하게 값을 넘길 수 있습니다.