File-Based Routing

TanStack Router의 대부분의 문서는 파일 기반 라우팅을 위한 내용으로 작성되었으며, 파일 기반 라우팅을 구성하는 방법과 그 작동 원리의 기술적 세부 사항을 자세히 이해하도록 돕기 위해 작성되었습니다. 파일 기반 라우팅은 TanStack Router를 구성하는 권장 방식이지만, 선호한다면 코드 기반 라우팅을 사용할 수도 있습니다.

[!NOTE] 🧠 파일 기반 라우팅이 어떻게 작동하는지 이미 익숙하고 설정 지침을 찾고 있다면 Installation 섹션으로 바로 건너뛸 수 있습니다. 또는 구성 옵션을 찾고 있다면 Options 섹션으로 건너뛰세요.

What is File-Based Routing?

파일 기반 라우팅은 파일 시스템을 사용하여 경로를 구성하는 방법입니다. 코드로 경로 구조를 정의하는 대신, 파일과 디렉토리를 사용해 애플리케이션의 경로 계층 구조를 나타낼 수 있습니다. 이를 통해 여러 가지 이점을 제공합니다:

• 간결함: 파일 기반 라우팅은 시각적으로 직관적이고, 초보자와 경험 많은 개발자 모두에게 이해하기 쉽습니다.
• 조직화: 경로가 애플리케이션의 URL 구조를 반영하는 방식으로 구성됩니다.
• 확장성: 애플리케이션이 성장함에 따라 파일 기반 라우팅은 새 경로를 추가하고 기존 경로를 유지 관리하기 쉽게 만듭니다.
• 코드 분할: 파일 기반 라우팅을 통해 TanStack Router는 자동으로 경로를 코드 분할하여 성능을 향상시킵니다.
• 타입 안전성: 파일 기반 라우팅은 경로의 타입 연결을 생성하고 관리함으로써 타입 안전성을 높입니다. 이는 코드 기반 라우팅을 사용하는 경우 번거로울 수 있는 작업입니다.
• 일관성: 파일 기반 라우팅은 경로에 대한 일관된 구조를 강제하여 애플리케이션을 유지하고 업데이트하기 쉽고 프로젝트 간 이동이 용이합니다.

/s or .s?

디렉토리는 오래전부터 경로 계층 구조를 나타내는 데 사용되었지만, 파일 기반 라우팅은 파일 이름에 . 문자를 사용해 경로 중첩을 나타내는 추가 개념을 도입합니다. 이를 통해 깊게 중첩된 몇몇 경로를 위해 디렉토리를 생성하지 않고도, 더 넓은 경로 계층 구조에 디렉토리를 계속 사용할 수 있습니다. 예제를 살펴보겠습니다!

Directory Routes

디렉토리는 경로 계층 구조를 나타내는 데 사용될 수 있습니다. 이는 여러 경로를 논리적 그룹으로 조직화하는 데 유용하며, 깊게 중첩된 경로 그룹의 파일 이름 길이를 줄이는 데에도 도움이 됩니다:

Flat Routes

평면 라우팅은 경로 중첩 수준을 나타내기 위해 . 문자를 사용할 수 있는 기능을 제공합니다. 이는 고유하고 깊게 중첩된 많은 경로를 보유하면서 각 경로마다 디렉토리를 생성하지 않으려는 경우 유용합니다:

Mixed Flat and Directory Routes

100% 디렉토리 또는 평면 경로 구조가 프로젝트에 가장 적합하지 않을 가능성이 매우 높습니다. 따라서 TanStack Router는 평면 경로와 디렉토리 경로를 혼합하여 두 방식의 장점을 적절히 활용할 수 있는 경로 트리를 만들 수 있도록 지원합니다:

평면 경로와 디렉토리 경로를 함께 사용하여 프로젝트의 요구에 맞는 유연한 경로 트리를 만들 수 있습니다.

[!TIP] 경로 파일의 위치를 사용자 지정하거나 경로 검색을 완전히 재정의하려면 Virtual File Routes를 사용해 프로그래밍 방식으로 경로 트리를 생성하면서 파일 기반 라우팅의 강력한 이점을 활용할 수 있습니다.

Dynamic Path Params

Dynamic path params를 사용하면 평면 및 디렉토리 경로 모두에서 URL 경로의 동적 세그먼트를 매칭하는 경로를 생성할 수 있습니다. Dynamic path params는 파일 이름에서 $ 문자로 표시됩니다:

Dynamic path params에 대한 자세한 내용은 Path Params 가이드를 참고하세요.

Pathless Routes

Pathless routes는 URL 경로 없이 로직 또는 컴포넌트로 자식 경로를 래핑합니다. Pathless routes는 파일 이름에서 _ 문자로 표시됩니다:

Pathless routes에 대해 자세히 알아보려면 Routing Concepts - Pathless Routes 가이드를 참고하세요.

File Naming Conventions

파일 기반 라우팅을 사용하려면 경로가 올바르게 생성되도록 몇 가지 간단한 파일 이름 규칙을 따라야 합니다. 이러한 규칙으로 구현되는 개념에 대한 자세한 내용은 Route Trees & Nesting 가이드에서 다룹니다.

[!IMPORTANT] > /api로 시작하는 경로는 예약되어 있으므로 파일 기반 라우팅에 사용할 수 없습니다. 이러한 경로는 TanStack Start의 API 경로에서 사용할 수 있도록 예약되어 있습니다. 파일 기반 라우팅과 함께 TanStack Router를 사용하는 경우 /api로 시작하는 경로가 필요하다면 apiBase 옵션을 다른 값으로 설정해야 합니다.

💡 기억하세요: 프로젝트의 파일 이름 규칙은 tsr.config.json에서 options으로 구성된 설정에 영향을 받을 수 있습니다. 기본적으로 routeFileIgnorePrefix 옵션은 -로 설정되어 있으므로, -로 시작하는 파일 및 디렉토리는 라우팅 대상에서 제외됩니다.

• __root.tsx
  • 루트 경로 파일은 반드시 __root.tsx로 이름 지어야 하며, 설정된 routesDirectory의 루트에 위치해야 합니다.
• . 구분자
  • 경로는 . 문자를 사용해 중첩 경로를 나타낼 수 있습니다. 예를 들어, blog.post는 blog의 자식으로 생성됩니다.
• $ 토큰
  • $ 토큰이 포함된 경로 세그먼트는 매개변수화되며, URL 경로 이름에서 값을 추출하여 경로 param으로 사용합니다.
• _ 접두사
  • _ 접두사가 포함된 경로 세그먼트는 레이아웃 경로로 간주되며, URL 경로 이름과 일치하는 자식 경로를 매칭할 때 사용되지 않습니다.
• _ 접미사
  • _ 접미사가 포함된 경로 세그먼트는 부모 경로에 중첩되지 않고 독립적인 경로로 처리됩니다.
• (folder) 디렉토리 이름 패턴
  • 이 패턴과 일치하는 디렉토리는 경로 그룹으로 처리되어 해당 디렉토리가 경로의 URL 경로에 포함되지 않도록 합니다.
• index 토큰
  • index 토큰으로 끝나는 경로 세그먼트는 부모 경로와 URL 경로 이름이 정확히 일치할 때 매칭됩니다. 이는 indexToken 구성 옵션을 통해 설정할 수 있습니다. 자세한 내용은 options를 참조하세요.
• .route.tsx 파일 형식
  • 디렉토리를 사용해 경로를 구성할 때, route 접미사를 사용하여 디렉토리 경로에 경로 파일을 생성할 수 있습니다. 예를 들어, blog.post.route.tsx 또는 blog/post/route.tsx는 /blog/post 경로의 경로 파일로 사용할 수 있습니다. 이는 routeToken 구성 옵션을 통해 설정할 수 있습니다. 자세한 내용은 options를 참조하세요.
• .lazy.tsx 파일 형식
  • lazy 접미사를 사용하여 경로의 컴포넌트를 코드 분할할 수 있습니다. 예를 들어, blog.post.lazy.tsx는 blog.post 경로의 컴포넌트로 사용됩니다.

Installation

파일 기반 라우팅을 시작하려면 프로젝트의 번들러를 TanStack Router Plugin 또는 TanStack Router CLI를 사용하도록 구성해야 합니다.

파일 기반 라우팅을 활성화하려면 React를 사용하고 지원되는 번들러를 사용해야 합니다. TanStack Router는 현재 다음 번들러를 지원합니다:

• Vite
• Rspack/Rsbuild
• Webpack
• Esbuild
• 기타??? (특정 번들러에 대한 지원을 보고 싶다면 알려주세요)

TanStack Router의 파일 기반 라우팅을 지원되는 번들러 중 하나를 통해 사용할 때, 플러그인은 번들러의 개발 및 빌드 프로세스를 통해 자동으로 경로 구성을 생성합니다. 이는 TanStack Router의 경로 생성 기능을 사용하는 가장 쉬운 방법입니다.

번들러가 아직 지원되지 않는 경우, Discord 또는 GitHub에서 문의해 주세요. 걱정하지 마세요! @tanstack/router-cli 패키지를 사용하여 경로 트리 파일을 여전히 생성할 수 있습니다.

Configuration with Vite

Vite와 함께 파일 기반 라우팅을 사용하려면 @tanstack/router-plugin 패키지를 설치해야 합니다.

npm install -D @tanstack/router-plugin

설치 후 Vite 구성에 플러그인을 추가해야 합니다.

// vite.config.ts
import { defineConfig } from "vite";
import viteReact from "@vitejs/plugin-react";
import { TanStackRouterVite } from "@tanstack/router-plugin/vite";
 
// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    TanStackRouterVite(),
    viteReact(),
    // ...
  ],
});

또는 Quickstart Vite example (opens in a new tab)을 복제하여 시작할 수 있습니다.

[!WARNING] 이전의 @tanstack/router-vite-plugin 패키지를 사용 중인 경우, 여전히 사용할 수 있으며, 이 패키지는 @tanstack/router-plugin/vite로 대체됩니다. 그러나 @tanstack/router-plugin 패키지를 직접 사용하는 것을 권장합니다.

플러그인을 Vite 구성에 추가한 후 TanStack Router와 함께 파일 기반 라우팅을 사용할 준비가 완료되었습니다.

생성된 경로 트리 파일을 무시하는 것을 잊지 마세요. 자세한 내용은 Ignoring the generated route tree file 섹션을 참고하세요.

Configuration with Rspack/Rsbuild

Rspack 또는 Rsbuild와 함께 파일 기반 라우팅을 사용하려면 @tanstack/router-plugin 패키지를 설치해야 합니다.

npm install -D @tanstack/router-plugin

설치 후 구성에 플러그인을 추가해야 합니다.

// rsbuild.config.ts
import { defineConfig } from "@rsbuild/core";
import { pluginReact } from "@rsbuild/plugin-react";
import { TanStackRouterRspack } from "@tanstack/router-plugin/rspack";
 
export default defineConfig({
  plugins: [pluginReact()],
  tools: {
    rspack: {
      plugins: [TanStackRouterRspack()],
    },
  },
});

또는 Quickstart Rspack/Rsbuild example (opens in a new tab)을 복제하여 시작할 수 있습니다.

Rspack/Rsbuild 구성을 완료한 후 TanStack Router와 함께 파일 기반 라우팅을 사용할 준비가 완료되었습니다.

생성된 경로 트리 파일을 무시하는 것을 잊지 마세요. 자세한 내용은 Ignoring the generated route tree file 섹션을 참고하세요.

Configuration with Webpack

Webpack과 함께 파일 기반 라우팅을 사용하려면 @tanstack/router-plugin 패키지를 설치해야 합니다.

npm install -D @tanstack/router-plugin

설치 후 구성에 플러그인을 추가해야 합니다.

// webpack.config.ts
import { TanStackRouterWebpack } from "@tanstack/router-plugin/webpack";
 
export default {
  plugins: [TanStackRouterWebpack()],
};

또는 Quickstart Webpack example (opens in a new tab)을 복제하여 시작할 수 있습니다.

Webpack 구성을 완료한 후 TanStack Router와 함께 파일 기반 라우팅을 사용할 준비가 완료되었습니다.

생성된 경로 트리 파일을 무시하는 것을 잊지 마세요. 자세한 내용은 Ignoring the generated route tree file 섹션을 참고하세요.

Configuration with Esbuild

Esbuild와 함께 파일 기반 라우팅을 사용하려면 @tanstack/router-plugin 패키지를 설치해야 합니다.

npm install -D @tanstack/router-plugin

설치 후 구성에 플러그인을 추가해야 합니다.

// esbuild.config.js
import { TanStackRouterEsbuild } from "@tanstack/router-plugin/esbuild";
 
export default {
  // ...
  plugins: [TanStackRouterEsbuild()],
};

또는 Quickstart Esbuild example (opens in a new tab)을 복제하여 시작할 수 있습니다.

Esbuild 구성을 완료한 후 TanStack Router와 함께 파일 기반 라우팅을 사용할 준비가 완료되었습니다.

생성된 경로 트리 파일을 무시하는 것을 잊지 마세요. 자세한 내용은 Ignoring the generated route tree file 섹션을 참고하세요.

Configuration with the TanStack Router CLI

TanStack Router CLI를 사용해 파일 기반 라우팅을 구성하려면 @tanstack/router-cli 패키지를 설치해야 합니다.

npm install -D @tanstack/router-cli

설치 후 package.json의 스크립트를 수정하여 CLI가 파일을 watch 및 generate할 수 있도록 설정합니다.

{
  "scripts": {
    "generate-routes": "tsr generate",
    "watch-routes": "tsr watch",
    "build": "npm run generate-routes && ...",
    "dev": "npm run watch-routes && ..."
  }
}

생성된 경로 트리 파일을 무시하는 것을 잊지 마세요. 자세한 내용은 Ignoring the generated route tree file 섹션을 참고하세요.

CLI를 설치하면 다음 명령어를 tsr 명령어로 사용할 수 있습니다.

Using the generate command

제공된 구성에 따라 프로젝트의 경로를 생성합니다.

tsr generate

Using the watch command

지정된 디렉토리를 지속적으로 감시하며 필요한 경우 경로를 다시 생성합니다.

사용법:

tsr watch

파일 기반 라우팅을 활성화하면 애플리케이션을 개발 모드로 시작할 때마다 TanStack Router는 설정된 routesDirectory를 감시하여 파일이 추가, 제거, 변경될 때마다 경로 트리를 생성합니다.

Disabling the TanStack Router Plugin during tests

⚠️ 참고: 테스트 실행 시 TanStack Router 플러그인을 비활성화하려면 현재 NODE_ENV에 따라 조건부로 플러그인을 추가할 수 있습니다.

// vite.config.ts
import { defineConfig } from "vite";
import viteReact from "@vitejs/plugin-react";
import { TanStackRouterVite } from "@tanstack/router-vite-plugin";
 
// vitest는 테스트 실행 시 자동으로 NODE_ENV를 'test'로 설정합니다.
const isTest = process.env.NODE_ENV === "test";
 
// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    !isTest && TanStackRouterVite(),
    viteReact(),
    // ...
  ],
});

Ignoring the generated route tree file

프로젝트가 린터 및/또는 포매터로 구성된 경우, 생성된 경로 트리 파일을 무시하고 싶을 수 있습니다. 이 파일은 TanStack Router에서 관리되므로 린터나 포매터에 의해 변경되지 않아야 합니다.

다음 리소스는 생성된 경로 트리 파일을 무시하는 데 도움이 됩니다:

• Prettier - https://prettier.io/docs/en/ignore.html#ignoring-files-prettierignore (opens in a new tab)
• ESLint - https://eslint.org/docs/latest/use/configure/ignore#ignoring-files (opens in a new tab)
• Biome - https://biomejs.dev/reference/configuration/#filesignore (opens in a new tab)

VSCode를 사용하는 경우, .vscode/settings.json 파일에 다음을 추가하여 생성된 경로 트리 파일을 편집기의 파일 감시에서 제외할 수 있습니다:

{
  "files.watcherExclude": {
    "**/routeTree.gen.ts": true
  }
}

Configuration

파일 기반 라우팅은 대부분의 프로젝트에 적합한 기본 설정을 제공합니다:

{
  "routesDirectory": "./src/routes",
  "generatedRouteTree": "./src/routeTree.gen.ts",
  "routeFileIgnorePrefix": "-",
  "quoteStyle": "single"
}

이 기본 설정이 프로젝트에 적합하다면 별도의 구성이 필요하지 않습니다! 하지만 구성을 사용자 지정해야 하는 경우, 프로젝트 디렉토리 루트에 tsr.config.json 파일을 생성하여 설정할 수 있습니다.

• tsr.config.json 파일은 프로젝트 디렉토리 루트에 배치해야 합니다.

Options

다음 옵션은 tsr.config.json 파일을 통해 구성할 수 있습니다:

[!IMPORTANT] > File Naming Conventions 섹션에서 사용되는 토큰과 일치하도록 routeFilePrefix, routeFileIgnorePrefix, 또는 routeFileIgnorePattern 옵션을 설정하지 마세요.

• routeFilePrefix

  • (선택 사항) 설정한 경우, 이 문자열로 시작하는 경로 파일 및 디렉토리만 라우팅에 포함됩니다.

• routeFileIgnorePrefix

  • (선택 사항, 기본값: -) 이 문자열로 시작하는 경로 파일 및 디렉토리는 무시됩니다. 기본적으로 -로 설정되어 있어 관련 파일을 포함하지만 경로 파일이 없는 디렉토리를 사용할 수 있습니다.

• routeFileIgnorePattern

  • (선택 사항) 경로 디렉토리에서 특정 파일 및 디렉토리를 무시합니다. 정규식 형식으로 사용할 수 있습니다. 예: .((css|const).ts)|test-page는 .css.ts, .const.ts 또는 test-page가 포함된 파일/디렉토리를 무시합니다.

• indexToken

  • (선택 사항, 기본값: 'index') File Naming Conventions에서 설명된 index 토큰을 사용자 지정할 수 있습니다.

• routeToken

  • (선택 사항, 기본값: 'route') File Naming Conventions에서 설명된 route 토큰을 사용자 지정할 수 있습니다.

• routesDirectory

  • (필수) 현재 작업 디렉토리 기준으로 경로를 포함하는 디렉토리입니다.

• generatedRouteTree

  • (필수) 생성된 경로 트리가 저장될 파일 경로입니다. 현재 작업 디렉토리를 기준으로 합니다.

• autoCodeSplitting

  • (선택 사항, 기본값: false) 모든 비중요 경로 구성 항목을 자동으로 코드 분할하도록 설정합니다.
  • 자세한 내용은 Using automatic code-splitting 가이드를 참조하세요.

• quoteStyle

  • (선택 사항, 기본값: single) 생성된 경로 트리 파일에서 단일 인용부호(single) 또는 이중 인용부호(double)를 사용할지를 설정합니다.

• semicolons

  • (선택 사항, 기본값: false) 생성된 경로 트리 파일에서 세미콜론 사용 여부를 설정합니다.

• apiBase

  • (선택 사항) API 경로의 기본 경로입니다. 기본값은 /api입니다.
  • 이 옵션은 TanStack Start의 API 경로에서 사용할 수 있도록 예약되었습니다.

• disableTypes

  • (선택 사항, 기본값: false) 경로 트리의 타입 생성을 비활성화합니다.
  • true로 설정된 경우, 생성된 경로 트리에 타입이 포함되지 않습니다.
  • true로 설정되고 generatedRouteTree 파일이 .ts 또는 .tsx로 끝나는 경우, 생성된 경로 트리는 대신 .js 파일로 작성됩니다.

• addExtensions

  • (선택 사항, 기본값: false) 생성된 경로 트리의 경로 이름에 파일 확장자를 추가합니다.

• disableLogging

  • (선택 사항, 기본값: false) 경로 생성 프로세스의 로깅을 비활성화합니다.

• routeTreeFileHeader

  • (선택 사항) 생성된 경로 트리 파일 콘텐츠의 맨 앞에 추가할 문자열 배열입니다.
  • 기본값:

  • [
      '/* eslint-disable */',
      '// @ts-nocheck',
      '// noinspection JSUnusedGlobalSymbols'
    ]

• routeTreeFileFooter

  • (선택 사항) 생성된 경로 트리 파일 콘텐츠의 맨 뒤에 추가할 문자열 배열입니다.
  • 기본값: []

• disableManifestGeneration

  • (선택 사항, 기본값: false) 경로 트리 매니페스트 생성을 비활성화합니다.

Route Inclusion / Exclusion

CLI는 routeFilePrefix 및 routeFileIgnorePrefix 옵션을 통해 특정 접두사로 시작하는 파일 및 디렉토리만 포함하거나, 특정 접두사로 시작하는 파일 및 디렉토리를 무시하도록 구성할 수 있습니다. 이는 동일한 디렉토리에서 라우팅 파일과 비라우팅 파일을 혼합하거나, 평면 구조를 사용할 때 특정 파일을 라우팅에서 제외하려는 경우에 특히 유용합니다.

Route Inclusion Example

라우팅에 ~로 시작하는 파일 및 디렉토리만 포함하려면 다음 구성을 사용할 수 있습니다:

🧠 ~ 접두사는 이 옵션을 사용할 때 일반적으로 권장됩니다. 이 기호는 유닉스 기반 시스템에서 홈 폴더 탐색과 일반적으로 연결되어 있을 뿐만 아니라, 파일 이름과 URL에서 유효한 문자이며, 디렉토리 상단에 파일을 배치하여 라우트로 쉽게 식별할 수 있습니다.

{
  "routeFilePrefix": "~",
  "routesDirectory": "./src/routes",
  "generatedRouteTree": "./src/routeTree.gen.ts"
}

이 구성을 사용하면 Posts.tsx, Post.tsx, 및 PostEditor.tsx 파일이 경로 생성 중 무시됩니다.

~__root.tsx
~posts.tsx
~posts
  ~index.tsx
  ~$postId.tsx
  ~$postId
    ~edit.tsx
    PostEditor.tsx
  Post.tsx
Posts.tsx

또한, 경로 파일이 없는 관련 파일을 포함하기 위해 디렉토리를 사용하는 것이 일반적입니다:

~__root.tsx
~posts.tsx
~posts
  ~index.tsx
  ~$postId.tsx
  ~$postId
    ~edit.tsx
    components
      PostEditor.tsx
  components
    Post.tsx
components
  Posts.tsx
utils
  Posts.tsx

Route Exclusion Example

라우팅에서 -로 시작하는 파일 및 디렉토리를 무시하려면 다음 구성을 사용할 수 있습니다:

🧠 - 접두사는 이 옵션을 사용할 때 일반적으로 권장됩니다. 마이너스 기호는 일반적으로 제거 또는 제외와 연결되어 있습니다.

{
  "routeFileIgnorePrefix": "-",
  "routesDirectory": "./src/routes",
  "generatedRouteTree": "./src/routeTree.gen.ts"
}

이 구성을 사용하면 Posts.tsx, Post.tsx, 및 PostEditor.tsx 파일이 경로 생성 중 무시됩니다.

__root.tsx
posts.tsx
posts
  index.tsx
  $postId.tsx
  $postId
    edit.tsx
    -PostEditor.tsx
  -Post.tsx
-Posts.tsx

또한, 경로 파일이 없는 관련 파일을 포함하기 위해 무시된 디렉토리를 사용하는 것이 일반적입니다:

__root.tsx
posts.tsx
posts
  index.tsx
  $postId.tsx
  $postId
    edit.tsx
    -components
      PostEditor.tsx
  -components
    Post.tsx
-components
  Posts.tsx
-utils
  Posts.tsx