본문으로 건너뛰기

라우터 만들기

createRouter 함수​

라우터를 사용할 준비가 되면 새 Router 인스턴스를 만들어야 합니다. 라우터 인스턴스는 TanStack Router의 핵심으로, 라우트 트리 관리, 라우트 매칭, 내비게이션 및 라우트 전환 조정을 담당합니다. 또한 라우터 전체 설정을 구성하는 곳이기도 합니다.

<!-- ::start:framework -->

React

src/router.tsx
import { createRouter } from '@tanstack/react-router'

const router = createRouter({
  // ...
})

Solid

src/router.tsx
import { createRouter } from '@tanstack/solid-router'

const router = createRouter({
  // ...
})

<!-- ::end:framework -->

라우트 트리​

Router 생성자에는 routeTree 옵션이 필요하다는 사실을 곧 알게 될 것입니다. 이 라우트 트리를 사용해 라우터가 라우트를 매칭하고 컴포넌트를 렌더링합니다.

파일 기반 라우팅 또는 코드 기반 라우팅을 사용했다면 라우트 트리를 createRouter 함수에 전달해야 합니다.

파일 시스템 라우트 트리​

권장하는 파일 기반 라우팅을 사용했다면 생성된 라우트 트리 파일이 기본 위치인 src/routeTree.gen.ts에 만들어졌을 가능성이 큽니다. 사용자 지정 위치를 사용했다면 해당 위치에서 라우트 트리를 가져와야 합니다.

import { routeTree } from './routeTree.gen'

코드 기반 라우트 트리​

코드 기반 라우팅을 사용했다면 루트 라우트의 addChildren 메서드를 사용해 라우트 트리를 직접 만들었을 가능성이 큽니다.

const routeTree = rootRoute.addChildren([
  // ...
])

라우터 타입 안전성​

[!IMPORTANT] 이 섹션을 건너뛰지 마세요! ⚠️

TanStack Router는 라이브러리에서 직접 가져오는 bare import처럼 예상하기 어려운 경우에도 TypeScript를 훌륭하게 지원합니다. 이를 위해 TypeScript의 Declaration Merging 기능을 사용해 라우터 타입을 등록해야 합니다. router 인스턴스 타입을 갖는 router 속성을 @tanstack/react-router의 Register 인터페이스에 추가해 등록합니다.

<!-- ::start:framework -->

React

src/router.tsx
declare module '@tanstack/react-router' {
  interface Register {
    // This infers the type of our router and registers it across your entire project
    router: typeof router
  }
}

Solid

src/router.tsx
declare module '@tanstack/solid-router' {
  interface Register {
    // This infers the type of our router and registers it across your entire project
    router: typeof router
  }
}

<!-- ::end:framework -->

라우터를 등록하면 라우팅과 관련된 모든 항목에서 프로젝트 전체에 타입 안전성이 적용됩니다.

404 찾을 수 없음 라우트​

이전 가이드에서 약속했듯이 이제 notFoundRoute 옵션을 살펴봅니다. 이 옵션은 적합한 매칭을 찾지 못했을 때 렌더링할 라우트를 구성하는 데 사용합니다. 404 페이지를 렌더링하거나 기본 라우트로 리디렉션할 때 유용합니다.

파일 기반 라우팅 또는 코드 기반 라우팅을 사용한다면 createRootRoute에 notFoundComponent 키를 추가해야 합니다.

export const Route = createRootRoute({
  component: () => (
    // ...
  ),
  notFoundComponent: () => <div>404 Not Found</div>,
});

기타 옵션​

Router 생성자에 전달할 수 있는 다른 옵션도 많습니다. 전체 목록은 API Reference에서 확인할 수 있습니다.