파일 기반 라우팅
TanStack Router 문서 대부분은 파일 기반 라우팅을 기준으로 작성되었으며, 파일 기반 라우팅을 구성하는 방법과 작동 방식의 기술적 세부 사항을 더 자세히 이해하도록 돕습니다. 파일 기반 라우팅은 TanStack Router를 구성할 때 선호되고 권장되는 방식이지만, 원한다면 코드 기반 라우팅을 사용할 수도 있습니다.
파일 기반 라우팅이란?
파일 기반 라우팅은 파일 시스템을 사용해 라우트를 구성하는 방법입니다. 코드를 통해 라우트 구조를 정의하는 대신 애플리케이션의 라우트 계층 구조를 나타내는 여러 파일과 디렉터리로 라우트를 정의할 수 있습니다. 다음과 같은 이점이 있습니다.
- 단순성: 파일 기반 라우팅은 시각적으로 직관적이며 초보자와 숙련된 개발자 모두 쉽게 이해할 수 있습니다.
- 구성: 라우트를 애플리케이션의 URL 구조를 반영하는 방식으로 구성합니다.
- 확장성: 애플리케이션이 성장해도 파일 기반 라우팅을 사용하면 새 라우트를 쉽게 추가하고 기존 라우트를 유지 관리할 수 있습니다.
- 코드 분할: 파일 기반 라우팅을 사용하면 TanStack Router가 더 나은 성능을 위해 라우트를 자동으로 코드 분할할 수 있습니다.
- 타입 안전성: 파일 기반 라우팅은 라우트의 타입 연결을 생성하고 관리해 타입 안전성의 한계를 높입니다. 이는 코드 기반 라우팅으로 처리하면 번거로운 작업일 수 있습니다.
- 일관성: 파일 기반 라우팅은 라우트에 일관된 구조를 적용하므로 애플리케이션을 유지 관리하고 업데이트하거나 다른 프로젝트로 옮기기 쉽습니다.
/일까요, .일까요?
디렉터리는 오랫동안 라우트 계층 구조를 나타내는 데 사용되었지만, 파일 기반 라우팅은 파일 이름에 . 문자를 사용해 라우트 중첩을 나타내는 개념을 추가합니다. 따라서 깊게 중첩된 일부 라우트에 대해 디렉터리를 만들지 않고 더 넓은 라우트 계층 구조에는 계속 디렉터리를 사용할 수 있습니다. 몇 가지 예제를 살펴보겠습니다.
디렉터리 라우트
디렉터리를 사용해 라우트 계층 구조를 나타낼 수 있습니다. 여러 라우트를 논리적 그룹으로 구성하고 깊게 중첩된 대규모 라우트 그룹의 파일 이름 길이를 줄이는 데 유용합니다.
다음 예제를 참고합니다.
| 파일 이름 | 라우트 경로 | 컴포넌트 출력 |
|---|---|---|
ʦ __root.tsx | <Root> | |
ʦ index.tsx | / (정확히 일치) | <Root><RootIndex> |
ʦ about.tsx | /about | <Root><About> |
ʦ posts.tsx | /posts | <Root><Posts> |
📂 posts | ||
┄ ʦ index.tsx | /posts (정확히 일치) | <Root><Posts><PostsIndex> |
┄ ʦ $postId.tsx | /posts/$postId | <Root><Posts><Post> |
📂 posts_ | ||
┄ 📂 $postId | ||
┄ ┄ ʦ edit.tsx | /posts/$postId/edit | <Root><EditPost> |
ʦ settings.tsx | /settings | <Root><Settings> |
📂 settings | <Root><Settings> | |
┄ ʦ profile.tsx | /settings/profile | <Root><Settings><Profile> |
┄ ʦ notifications.tsx | /settings/notifications | <Root><Settings><Notifications> |
ʦ _pathlessLayout.tsx | <Root><PathlessLayout> | |
📂 _pathlessLayout | ||
┄ ʦ route-a.tsx | /route-a | <Root><PathlessLayout><RouteA> |
┄ ʦ route-b.tsx | /route-b | <Root><PathlessLayout><RouteB> |
📂 files | ||
┄ ʦ $.tsx | /files/$ | <Root><Files> |
📂 account | ||
┄ ʦ route.tsx | /account | <Root><Account> |
┄ ʦ overview.tsx | /account/overview | <Root><Account><Overview> |
플랫 라우트
플랫 라우팅을 사용하면 .으로 라우트 중첩 수준을 나타낼 수 있습니다.
이는 깊게 중첩된 고유 라우트가 많고 각각에 대한 디렉터리 생성을 피하려는 경우에 유용합니다.
다음 예제를 참고합니다.
| 파일 이름 | 라우트 경로 | 컴포넌트 출력 |
|---|---|---|
ʦ __root.tsx | <Root> | |
ʦ index.tsx | / (정확히 일치) | <Root><RootIndex> |
ʦ about.tsx | /about | <Root><About> |
ʦ posts.tsx | /posts | <Root><Posts> |
ʦ posts.index.tsx | /posts (정확히 일치) | <Root><Posts><PostsIndex> |
ʦ posts.$postId.tsx | /posts/$postId | <Root><Posts><Post> |
ʦ posts_.$postId.edit.tsx | /posts/$postId/edit | <Root><EditPost> |
ʦ settings.tsx | /settings | <Root><Settings> |
ʦ settings.profile.tsx | /settings/profile | <Root><Settings><Profile> |
ʦ settings.notifications.tsx | /settings/notifications | <Root><Settings><Notifications> |
ʦ _pathlessLayout.tsx | <Root><PathlessLayout> | |
ʦ _pathlessLayout.route-a.tsx | /route-a | <Root><PathlessLayout><RouteA> |
ʦ _pathlessLayout.route-b.tsx | /route-b | <Root><PathlessLayout><RouteB> |
ʦ files.$.tsx | /files/$ | <Root><Files> |
ʦ account.tsx | /account | <Root><Account> |
ʦ account.overview.tsx | /account/overview | <Root><Account><Overview> |
플랫 라우트와 디렉터리 라우트 혼합
100% 디렉터리 또는 플랫 라우트 구조가 프로젝트에 가장 적합하지 않을 가능성이 높습니다. 그래서 TanStack Router는 두 방식이 적합한 곳에서 장점을 함께 활용하는 라우트 트리를 만들도록 플랫 라우트와 디렉터리 라우트를 혼합할 수 있게 합니다.
다음 예제를 참고합니다.
| 파일 이름 | 라우트 경로 | 컴포넌트 출력 |
|---|---|---|
ʦ __root.tsx | <Root> | |
ʦ index.tsx | / (정확히 일치) | <Root><RootIndex> |
ʦ about.tsx | /about | <Root><About> |
ʦ posts.tsx | /posts | <Root><Posts> |
📂 posts | ||
┄ ʦ index.tsx | /posts (정확히 일치) | <Root><Posts><PostsIndex> |
┄ ʦ $postId.tsx | /posts/$postId | <Root><Posts><Post> |
┄ ʦ $postId.edit.tsx | /posts/$postId/edit | <Root><Posts><Post><EditPost> |
ʦ settings.tsx | /settings | <Root><Settings> |
ʦ settings.profile.tsx | /settings/profile | <Root><Settings><Profile> |
ʦ settings.notifications.tsx | /settings/notifications | <Root><Settings><Notifications> |
ʦ account.tsx | /account | <Root><Account> |
ʦ account.overview.tsx | /account/overview | <Root><Account><Overview> |
플랫 라우트와 디렉터리 라우트를 함께 혼합해 두 방식이 적합한 곳에서 장점을 활용하는 라우트 트리를 만들 수 있습니다.
[!TIP] 기본 파일 기반 라우팅 구조가 필요에 맞지 않으면 가상 파일 라우트를 사용해 라우트의 소스를 제어하면서도 파일 기반 라우팅의 뛰어난 성능 이점을 얻을 수 있습니다.
파일 기반 라우팅 시작하기
파일 기반 라우팅을 시작하려면 프로젝트의 번들러가 TanStack Router Plugin 또는 TanStack Router CLI를 사용하도록 구성해야 합니다.
파일 기반 라우팅을 활성화하려면 지원되는 번들러와 함께 React를 사용해야 합니다. 아래 구성 가이드에 번들러가 나열되어 있는지 확인합니다.
React
Solid
지원되는 번들러 중 하나를 통해 TanStack Router의 파일 기반 라우팅을 사용하면 플러그인이 번들러의 개발 및 빌드 프로세스를 통해 라우트 구성을 자동으로 생성합니다. TanStack Router의 라우트 생성 기능을 사용하는 가장 쉬운 방법입니다.
번들러가 아직 지원되지 않으면 Discord 또는 GitHub에서 알려주시기 바랍니다.