라우팅

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	인덱스 라우트
/about	about.tsx	정적 라우트
	posts.tsx	"레이아웃" 라우트
/posts/	posts/index.tsx	인덱스 라우트
/posts/:postId	posts/$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 문서를 참조하세요.