본문으로 건너뛰기

라우팅

TanStack Start는 TanStack Router를 기반으로 구축되므로 TanStack Router의 모든 기능을 사용할 수 있습니다.

[!NOTE] TanStack Router의 기능과 역량을 자세히 알아보려면 TanStack Router 문서를 읽어보시기를 적극 권장합니다. 여기서 배우는 내용은 TanStack Router와 Start에서의 작동 방식을 개괄적으로 살펴보는 수준입니다.

라우터​

router.tsx 파일은 Start 내에서 사용되는 TanStack Router의 동작을 결정하는 파일입니다. 프로젝트의 src 디렉터리에 있습니다.

src/
├── router.tsx

여기에서 기본 프리로딩 기능부터 캐시의 오래됨 기준까지 모든 것을 구성할 수 있습니다.

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

// You must export a getRouter function that
// returns a new router instance each time
export function getRouter() {
  const router = createRouter({
    routeTree,
    scrollRestoration: true,
  })

  return router
}

파일 기반 라우팅​

Start는 적절한 코드 분할과 고급 타입 안전성을 보장하기 위해 TanStack Router의 파일 기반 라우팅 방식을 사용합니다.

라우트는 src/routes 디렉터리에서 찾을 수 있습니다.

src/
├── routes <-- This is where you put your routes
│   ├── __root.tsx
│   ├── index.tsx
│   ├── about.tsx
│   ├── posts.tsx
│   ├── posts/$postId.tsx

루트 라우트​

루트 라우트는 전체 트리에서 최상위에 있는 라우트이며, 다른 모든 라우트를 자식으로 포함합니다. src/routes/__root.tsx 파일에 있으며 이름은 반드시 __root.tsx이어야 합니다.

src/
├── routes
│   ├── __root.tsx <-- The root route
  • 경로가 없으며 항상 일치합니다
  • 해당 component은 항상 렌더링됩니다
  • 여기에서 문서 셸(예: <html>, <body> 등)을 렌더링합니다
  • 항상 렌더링되므로 애플리케이션 셸을 구성하고 전역 로직을 처리하기에 가장 적합한 위치입니다
// src/routes/__root.tsx
import {
  Outlet,
  createRootRoute,
  HeadContent,
  Scripts,
} from '@tanstack/react-router'
import type { ReactNode } from 'react'

export const Route = createRootRoute({
  head: () => ({
    meta: [
      {
        charSet: 'utf-8',
      },
      {
        name: 'viewport',
        content: 'width=device-width, initial-scale=1',
      },
      {
        title: 'TanStack Start Starter',
      },
    ],
  }),
  component: RootComponent,
})

function RootComponent() {
  return (
    <RootDocument>
      <Outlet />
    </RootDocument>
  )
}

function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  )
}

<body> 태그 하단에 있는 Scripts 컴포넌트를 확인합니다. 이 컴포넌트는 애플리케이션의 모든 클라이언트 측 JavaScript를 로드하는 데 사용되며, 올바른 작동을 위해 항상 포함해야 합니다.

HeadContent 컴포넌트​

HeadContent 컴포넌트는 문서의 head, title, meta, link 및 head 관련 script 태그를 렌더링하는 데 사용됩니다.

루트 라우트 레이아웃의 <head> 태그에서 렌더링해야 합니다.

Outlet 컴포넌트​

Outlet 컴포넌트는 다음으로 일치할 가능성이 있는 자식 라우트를 렌더링하는 데 사용됩니다. <Outlet />는 props를 받지 않으며 라우트의 컴포넌트 트리 내 어디에서나 렌더링할 수 있습니다. 일치하는 자식 라우트가 없으면 <Outlet />는 null을 렌더링합니다.

Scripts 컴포넌트​

Scripts 컴포넌트는 문서의 body 스크립트를 렌더링하는 데 사용됩니다.

루트 라우트 레이아웃의 <body> 태그 안에 렌더링해야 합니다.

라우트 트리 생성​

프로젝트에서 routeTree.gen.ts 파일을 볼 수 있습니다.

src/
├── routeTree.gen.ts <-- The generated route tree file

이 파일은 TanStack Start를 실행할 때(npm run dev 또는 npm run start을 통해) 자동으로 생성됩니다. 이 파일에는 생성된 라우트 트리와 TanStack Start의 타입 안전성을 매우 빠르게 유지하면서 모든 타입을 추론할 수 있게 하는 몇 가지 TS 유틸리티가 포함되어 있습니다.

중첩 라우팅​

TanStack Router는 중첩 라우팅을 사용하여 URL을 렌더링할 올바른 컴포넌트 트리와 일치시킵니다.

예를 들어 다음과 같은 라우트가 있다고 가정합니다.

routes/
├── __root.tsx <-- Renders the <Root> component
├── posts.tsx <-- Renders the <Posts> component
├── posts.$postId.tsx <-- Renders the <Post> component

URL은 다음과 같습니다: /posts/123

컴포넌트 트리는 다음과 같습니다.

<Root>
  <Posts>
    <Post />
  </Posts>
</Root>

라우트 유형​

프로젝트에서 생성할 수 있는 라우트 유형은 몇 가지가 있습니다.

  • 인덱스 라우트 - URL이 라우트의 경로와 정확히 같을 때 일치합니다
  • 동적/와일드카드/Splat 라우트 - 애플리케이션에서 사용할 수 있도록 URL 경로의 일부 또는 전체를 변수로 동적으로 캡처합니다

라우트를 그룹화하고 구성하는 데 사용할 수 있는 유틸리티 라우트 유형도 몇 가지 있습니다

  • 경로 없는 레이아웃 라우트(경로에 중첩하지 않고 라우트 그룹에 레이아웃이나 로직을 적용합니다)
  • 비중첩 라우트(상위 라우트와의 중첩을 해제하고 자체 컴포넌트 트리를 렌더링합니다)
  • 그룹화된 라우트(경로 계층 구조에 영향을 주지 않고 구성을 위해 디렉터리에서 라우트를 함께 그룹화합니다)

라우트 트리 구성​

라우트 트리는 src/routes 디렉터리에서 구성됩니다.

파일 라우트 생성​

라우트를 생성하려면 생성하려는 라우트의 경로에 해당하는 새 파일을 만듭니다. 예:

경로파일명유형
/index.tsx인덱스 라우트
/aboutabout.tsx정적 라우트
posts.tsx"레이아웃" 라우트
/posts/posts/index.tsx인덱스 라우트
/posts/:postIdposts/$postId.tsx동적 라우트
/rest/*rest/$.tsx와일드카드 라우트

라우트 정의​

라우트를 정의하려면 createFileRoute 함수를 사용하여 라우트를 Route 변수로 내보냅니다.

예를 들어 /posts/:postId 라우트를 처리하려면 여기에 posts/$postId.tsx 파일을 생성합니다:

src/
├── routes
│   ├── posts/$postId.tsx

그런 다음 라우트를 다음과 같이 정의합니다:

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

export const Route = createFileRoute('/posts/$postId')({
  component: PostComponent,
})

[!NOTE] createFileRoute에 전달되는 경로 문자열은 TanStack Router Bundler Plugin 또는 Router CLI를 통해 라우터가 자동으로 작성하고 관리합니다. 따라서 새 라우트를 생성하거나 라우트를 이동하거나 이름을 변경하면 경로가 자동으로 업데이트됩니다.

이것은 단지 "시작"일 뿐입니다​

지금까지 TanStack Router를 사용하여 라우트를 구성하는 방법을 개괄적으로 살펴보았습니다. 자세한 내용은 TanStack Router 문서를 참조하세요.