파일 기반 라우팅 API 레퍼런스

TanStack Router의 파일 기반 라우팅은 매우 유연하며 프로젝트 요구 사항에 맞게 구성할 수 있습니다.

구성 옵션

파일 기반 라우팅을 구성하는 데 다음 옵션을 사용할 수 있습니다.

• routesDirectory (필수)
• generatedRouteTree (필수)
• virtualRouteConfig
• routeFilePrefix
• routeFileIgnorePrefix
• routeFileIgnorePattern
• indexToken
• routeToken
• quoteStyle
• semicolons
• autoCodeSplitting
• disableTypes
• addExtensions
• disableLogging
• routeTreeFileHeader
• routeTreeFileFooter
• enableRouteTreeFormatting
• tmpDir

[!WARNING] routeFilePrefix, routeFileIgnorePrefix 또는 routeFileIgnorePattern 옵션을 파일 이름 지정 규칙 가이드에서 사용하는 토큰과 일치하도록 설정하지 마세요. 예기치 않은 동작이 발생할 수 있습니다.

routesDirectory (필수)

라우트 파일이 있는 디렉터리의 경로이며 cwd(현재 작업 디렉터리)를 기준으로 합니다.

기본값은 다음과 같으며 빈 string이나 undefined로 설정할 수 없습니다.

./src/routes

generatedRouteTree (필수)

생성된 라우트 트리를 저장할 파일의 경로이며 cwd(현재 작업 디렉터리)를 기준으로 합니다.

기본값은 다음과 같으며 빈 string이나 undefined로 설정할 수 없습니다.

./src/routeTree.gen.ts

disableTypes를 true로 설정하면 생성된 라우트 트리가 .ts 대신 .js 확장자로 저장됩니다.

virtualRouteConfig

이 옵션은 가상 파일 라우트 기능을 구성하는 데 사용합니다. 자세한 내용은 "가상 파일 라우트" 가이드를 참고합니다.

기본값은 undefined입니다.

routeFilePrefix

이 옵션은 라우트 디렉터리에서 라우트 파일을 식별하는 데 사용합니다. 즉, 이 접두사로 시작하는 파일만 라우팅 대상으로 간주합니다.

기본값은 ``이므로 라우트 디렉터리의 모든 파일을 라우팅 대상으로 간주합니다.

routeFileIgnorePrefix

이 옵션은 라우트 디렉터리에서 특정 파일과 디렉터리를 무시하는 데 사용합니다. 라우팅 대상으로 간주하지 않을 특정 파일이나 디렉터리를 명시적으로 포함하려는 경우 유용합니다.

기본값은 -입니다.

이 옵션을 사용하면 라우트 파일이 아닌 관련 파일을 함께 배치하는 다음과 같은 구조를 만들 수 있습니다.

src/routes
├── posts
│   ├── -components  // Ignored
│   │   ├── Post.tsx
│   ├── index.tsx
│   ├── route.tsx

routeFileIgnorePattern

이 옵션은 라우트 디렉터리에서 특정 파일과 디렉터리를 무시하는 데 사용합니다. 정규 표현식 형식으로 사용할 수 있습니다. 예를 들어 .((css|const).ts)|test-page는 이름에 .css.ts, .const.ts 또는 test-page가 포함된 파일/디렉터리를 무시합니다.

기본값은 undefined입니다.

routeToken

라우팅 개념 가이드에서 설명했듯이 레이아웃 라우트는 지정된 경로에 렌더링되고 자식 라우트는 레이아웃 라우트 안에 렌더링됩니다. routeToken은 라우트 디렉터리에서 레이아웃 라우트 파일을 식별하는 데 사용합니다.

기본값은 route입니다.

🧠 다음 파일 이름은 동일한 런타임 URL을 나타냅니다.

src/routes/posts.tsx -> /posts
src/routes/posts.route.tsx -> /posts
src/routes/posts/route.tsx -> /posts

routeToken에 정규식 패턴 사용

리터럴 문자열 대신 정규 표현식 패턴을 사용해 여러 레이아웃 라우트 이름 지정 규칙을 매칭할 수 있습니다. 파일 이름을 더 유연하게 지정하려는 경우 유용합니다.

tsr.config.json(JSON 구성)에서는 regex와 선택적 flags 속성이 있는 객체를 사용합니다.

{
  "routeToken": { "regex": "[a-z]+-layout", "flags": "i" }
}

코드(인라인 구성)에서는 네이티브 RegExp를 사용할 수 있습니다.

{
  routeToken: /[a-z]+-layout/i
}

[a-z]+-layout 정규식 패턴을 사용하면 dashboard.main-layout.tsx, posts.protected-layout.tsx 또는 admin.settings-layout.tsx와 같은 파일 이름을 모두 레이아웃 라우트로 인식합니다.

[!NOTE] 정규식은 라우트 경로의 마지막 세그먼트 전체와 매칭합니다. 예를 들어 routeToken: { "regex": "[a-z]+-layout" }인 경우:

• dashboard.main-layout.tsx는 매칭됩니다(main-layout이 전체 세그먼트임).
• dashboard.my-layout-extra.tsx는 매칭되지 않습니다(세그먼트가 my-layout만이 아니라 my-layout-extra임).

indexToken

라우팅 개념 가이드에서 설명했듯이 인덱스 라우트는 URL 경로가 부모 라우트와 정확히 같을 때 매칭되는 라우트입니다. indexToken은 라우트 디렉터리에서 인덱스 라우트 파일을 식별하는 데 사용합니다.

기본값은 index입니다.

🧠 다음 파일 이름은 동일한 런타임 URL을 나타냅니다.

src/routes/posts.index.tsx -> /posts/
src/routes/posts/index.tsx -> /posts/

indexToken에 정규식 패턴 사용

routeToken과 마찬가지로 indexToken에 정규 표현식 패턴을 사용해 여러 인덱스 라우트 이름 지정 규칙을 매칭할 수 있습니다.

tsr.config.json(JSON 구성):

{
  "indexToken": { "regex": "[a-z]+-page" }
}

코드(인라인 구성):

{
  indexToken: /[a-z]+-page/
}

[a-z]+-page 정규식 패턴을 사용하면 home-page.tsx, posts.list-page.tsx 또는 dashboard.overview-page.tsx와 같은 파일 이름을 모두 인덱스 라우트로 인식합니다.

정규식 토큰 이스케이프

정규식 토큰을 사용할 때도 세그먼트를 대괄호로 감싸 토큰으로 처리되지 않도록 이스케이프할 수 있습니다. 예를 들어 indexToken이 { "regex": "[a-z]+-page" }이고 home-page라는 리터럴 라우트 세그먼트를 사용하려면 파일 이름을 [home-page].tsx로 지정합니다.

quoteStyle

생성된 라우트 트리를 생성할 때와 새 라우트를 처음 만들 때 해당 파일을 여기서 지정한 인용 부호 스타일로 포맷합니다.

기본값은 single입니다.

[!TIP] 충돌을 피하려면 린터와 포매터에서 생성된 라우트 트리 파일의 경로를 무시해야 합니다.

semicolons

생성된 라우트 트리를 생성할 때와 새 라우트를 처음 만들 때 이 옵션을 true로 설정하면 해당 파일을 세미콜론과 함께 포맷합니다.

기본값은 false입니다.

[!TIP] 충돌을 피하려면 린터와 포매터에서 생성된 라우트 트리 파일의 경로를 무시해야 합니다.

autoCodeSplitting

이 기능은 TanStack Router Bundler Plugin을 사용하는 경우에만 사용할 수 있습니다.

이 옵션은 중요하지 않은 라우트 구성 항목의 자동 코드 분할을 활성화하는 데 사용합니다. 자세한 내용은 "자동 코드 분할" 가이드를 참고합니다.

• 기본값은 false입니다.

[!IMPORTANT] TanStack Router의 다음 메이저 릴리스(v2)에서는 이 값의 기본값이 true가 됩니다.

disableTypes

이 옵션은 라우트 트리의 타입 생성을 비활성화하는 데 사용합니다.

true로 설정하면 생성된 라우트 트리에 타입이 포함되지 않으며 .ts 파일 대신 .js 파일로 작성됩니다.

• 기본값은 false입니다.

addExtensions

• 타입: boolean | string
• 기본값: false

이 옵션은 생성된 라우트 트리의 가져오기 경로에 사용할 파일 확장자를 제어합니다.

• false — 가져오기 경로에서 확장자를 제거합니다(예: './routes/posts').
• true — 원래 파일 확장자를 유지합니다(예: './routes/posts.tsx').
• string — 원래 확장자를 지정한 확장자로 바꿉니다(예: 'js'는 './routes/posts.js'를 생성합니다).

프로젝트에서 ESM을 사용하는 경우 문자열을 전달하면 유용합니다. Node.js ESM은 원본 파일이 .ts 또는 .tsx여도 가져오기에 .js 확장자가 필요하기 때문입니다.

// Example: replace .tsx/.ts extensions with .js in generated imports
TanStackRouterVite({
  addExtensions: 'js',
})

disableLogging

이 옵션은 라우트 생성 프로세스의 콘솔 로깅을 끕니다.

• 기본값은 false입니다.

routeTreeFileHeader

이 옵션을 사용하면 생성된 라우트 트리 파일의 시작 부분에 콘텐츠를 추가할 수 있습니다.

기본값은 다음과 같습니다.

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

routeTreeFileFooter

이 옵션을 사용하면 생성된 라우트 트리 파일의 끝에 콘텐츠를 추가할 수 있습니다.

기본값은 다음과 같습니다.

[]

enableRouteTreeFormatting

이 옵션은 생성된 라우트 트리 파일의 포맷팅 함수를 켭니다. 대규모 프로젝트에서는 시간이 오래 걸릴 수 있습니다.

• 기본값은 true입니다.

tmpDir

원자적 파일 쓰기(라우트 파일 및 생성된 라우트 트리 파일)는 먼저 임시 파일을 만든 다음 실제 위치로 이름을 바꾸는 방식으로 구현합니다.

이 구성 옵션으로 해당 임시 파일을 만들 때 사용할 임시 디렉터리의 경로를 구성할 수 있습니다. 상대 경로인 경우 현재 작업 디렉터리를 기준으로 해석합니다. 이 값을 설정하지 않으면 process.env.TSR_TMP_DIR을 사용합니다. process.env.TSR_TMP_DIR이 설정되지 않으면 현재 작업 디렉터리를 기준으로 .tanstack/tmp를 기본값으로 사용합니다.