TanStack Router?
React Query(현 TanStack Query)로 유명한 Tanner Linsley가 개발한 헤드리스(Headless) 라우팅 라이브러리
헤드리스(Headless): UI나 특정 프레임워크에 종속되지 않고, 핵심 라우팅 로직만 제공하여 개발자가 자유롭게 UI와 통합할 수 있게 함
현재 React를 주요 타겟으로 하고 있으며(@tanstack/react-router), 추후 다른 프론트엔드 프레임워크(Vue, Svelte 등)로도 확장할 것으로 보인다.
특징 및 장단점
파일 기반 라우팅 지원
TanStack Router는 "파일 기반 라우팅" 기능을 제공하며, 권장하고 있다.
Next.js를 사용해 본 경험이 있다면, 폴더 구조에 따라 자동으로 URL Path를 만들어주는 "파일 기반 라우팅"이 편리하다고 생각하는 경우가 많을 것이라 생각한다.
TanStack Router는 Next.js와 유사한 파일 기반 라우팅을 제공하기 때문에 약간의 러닝커브를 거친 후에 편리하게 사용할 수 있었다. 👍
장점
- React Router와 유사한 기능을 대부분 제공 (코드 기반 라우팅 등)
- 파일 기반 라우팅이 익숙한 개발자라면 편리함
- loader api, prefetch 등의 편리한 기능 제공
- url, loader 등에 대한 타입 안정성
- vite 등의 빌드 도구와 사용하기 쉬움
단점
- 학습 난이도 높음
- React Router 등에 비해 커뮤니티, 문서화 부족
- 정식 버전이 출시된 지 얼마 되지 않아 변화가 많을 수 있음
검색을 통해 블로그를 참고하려고 해도 글이 많지 않고, 제대로 정리된 글도 찾기 힘들어서 공식문서를 읽고 직접 하나씩 실행해보면서 사용법을 익혔다...
사용법이 정리된 블로그들을 봐도 생략된 과정이 많고, 다른 사람이 알아볼만한 글이 아니었음 😠
사용법 (Vite + TanStack Router)
react를 타겟으로 하며, 파일 기반 라우팅에 대해서만 정리함
코드 기반 라우팅은 React Router와 유사하며, TanStack 공식문서 참고
실행 흐름
설치 및 실행에 앞서 대략적인 흐름을 아는 것이 이해에 도움이 될 것 같다.
(여러 글들에서 routeTree.gen.ts 파일 자동 생성 등에 대한 내용이 없어 한참 헤맸음...)
- 패키지 설치 및
vite.config.ts설정 main.tsx에서 router 생성 및<RouterProvider />컴포넌트 추가
(routeTree 파일이 아직 생성되기 전이므로, eslint 오류가 표시됨.)- routes 폴더에
__root.tsx파일 생성 (2-1 ~ 2-3 생략 가능)
2-1.tsr generate명령어 실행 (@tanstack/router-cli의 기능)
->__root.tsx에 코드가 자동으로 추가됨 +routeTree.gen.ts생성됨
2-3. url 경로에 맞는index.tsx,_layout.tsx등 파일 생성 및 generate 명령어 실행 vite dev명령어 실행
->routeTree.gen.ts생성됨
3-1. 개발 서버 구동 중에index.tsx등의 파일을 생성하면 자동으로 코드가 추가됨- 필요하다면 추가 설정 (.prettierignore, .vscode/settings.json 등)
vite 프로젝트 생성
npm create vite@latest실행 후 안내를 따라 React, TypeScript를 사용하도록 설정함
패키지 설치
npm i @tanstack/react-router
npm i -D @tanstack/react-router-devtools
npm i -D @tanstack/router-plugin # vite에 적용할 plugin
npm i -D @tanstack/router-cli # vite 없이 별도로 routeTree를 생성하기 위함TanStack 공식문서에는 react-router-devtools는 npm install @tanstack/react-router-devtools로 되어있지만, devtools 라는 이름처럼 개발 과정에서 상태를 확인하기 위한 도구이므로 devDependencies(-D)로 설치하였음
사전 설정
vite.config.ts
import { TanStackRouterVite } from '@tanstack/router-plugin/vite';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
TanStackRouterVite({
target: 'react',
autoCodeSplitting: true,
routesDirectory: './src/routes',
}),
react(),
],
});routesDirectory 설정을 생략하면 기본값이 routes 폴더로 지정된다.
필요하다면 routeToken, indexToken 등의 설정을 통해 파일명 컨벤션이나 폴더 등을 원하는대로 변경할 수 있다.
main.tsx
// ...
import { RouterProvider, createRouter } from '@tanstack/react-router';
import { routeTree } from './routeTree.gen';
const router = createRouter({
routeTree,
});
createRoot(document.getElementById('root')!).render(
<StrictMode>
// ...
<RouterProvider router={router} />
// ...
</StrictMode>
);__root.tsx 및 routeTree 생성
routes 폴더 내부에 __route.tsx가 존재해야 routeTree를 생성할 수 있다.
아래와 같이 파일을 생성하자.
그 다음, npx tsr generate 혹은 npm run dev(npx vite dev) 실행
-> routeTree.gen.ts 파일이 자동으로 생성되며 main.tsx의 eslint 오류가 사라짐 + __root.tsx에 코드가 자동으로 채워짐
__root.tsx
import * as React from 'react'
import { Outlet, createRootRoute } from '@tanstack/react-router'
export const Route = createRootRoute({
component: RootComponent,
})
function RootComponent() {
return (
<React.Fragment>
<div>Hello "__root"!</div>
<Outlet />
</React.Fragment>
)
}추가 설정
vite dev로 개발서버 구동 중에 routes 폴더 내부의 파일들의 이름을 변경하거나 이동하게 되면, routeTree.gen.ts가 즉시 변경되는데, prettier의 영향을 받게 된다.
따라서 아래의 두 가지 방법을 통해 오류를 방지하였다.
.prettierignore 파일에 routeTree.gen.ts 추가
// .prettierignore
routeTree.gen.ts.vscode 폴더의 setting.json에 설정 코드 추가
{
...
"files.readonlyInclude": {
"**/routeTree.gen.ts": true
},
"files.watcherExclude": {
"**/routeTree.gen.ts": true
},
"search.exclude": {
"**/routeTree.gen.ts": true
}
...
}⚠️ 주의
개발서버 구동 중 파일 이동 or 파일명 변경 시 vscode에서 "~~에 대한 가져오기를 업데이트하시겠습니까"라는 문구의 prompt가 뜨는데, "예"를 선택 시routeTree.gen.ts파일이 이상하게 수정되어 오류가 발생하는 경우가 있다.
-> "아니요"를 선택하거나, 오류 발생 시routeTree.gen.ts를 다시 생성해야 함
파일명 컨벤션
index.tsx: 해당 경로의 기본 페이지 ("/example/")route.tsx: 해당 경로의 페이지 ("/example" - 정확히 그 경로만)
-> 내부에<Outlet />을 포함하면, layout의 역할을 할 수 있음example.tsx등:/example/route.tsx와 동일index.lazy.tsx: lazy loading 페이지 -> React Route에서 react의 lazy를 사용하는 것과 동일_pathless-layout(.tsx): url에 포함되지 않는 레이아웃용(?) 파일 및 폴더(pathless-route): url에 포함되지 않는 폴더
File Naming Convention - TanStack Router https://tanstack.com/router/latest/docs/framework/react/routing/file-naming-conventions
참고
[공식문서] TanStack Router
https://tanstack.com/router/latest
TanStack Router의 추가적인 기능들은 추후 포스팅할 예정
