React Location에서 마이그레이션

React Location에서 마이그레이션을 시작하기 전에 TanStack Router에서 사용하는 라우팅 개념과 설계 결정을 잘 이해하는 것이 중요합니다.

React Location과 TanStack Router의 차이점

React Location과 TanStack Router는 많은 설계 결정 개념을 공유하지만, 알아두어야 할 몇 가지 주요 차이점이 있습니다.

• React Location은 라우트의 타입을 추론할 때 _generics_를 사용하는 반면, TanStack Router는 타입을 추론할 때 _module declaration merging_을 사용합니다.
• React Location에서는 하나의 라우트 정의 배열로 라우트를 구성하는 반면, TanStack Router에서는 루트 라우트로 시작하는 라우트 정의 트리로 라우트를 구성합니다.
• TanStack Router에서 라우트를 정의하는 권장 방법은 파일 기반 라우팅인 반면, React Location에서는 코드 기반 방식으로 하나의 파일에서만 라우트를 정의할 수 있습니다.
  • TanStack Router도 라우트를 정의하는 코드 기반 방식을 지원하지만 대부분의 사용 사례에는 권장하지 않습니다. 그 이유는 파일 기반 라우팅을 라우트 정의의 권장 방식으로 사용하는 이유에서 자세히 알아볼 수 있습니다.

마이그레이션 가이드

이 가이드에서는 React Location Basic 예제를 파일 기반 라우팅을 사용하는 TanStack Router로 마이그레이션하는 과정을 살펴봅니다. 최종 목표는 원래 예제와 동일한 기능을 구현하는 것입니다(스타일링과 라우팅과 관련 없는 다른 코드는 생략합니다).

[!TIP] 라우트를 정의하는 코드 기반 방식을 사용하려면 코드 기반 라우팅 가이드를 읽습니다.

1단계: TanStack Router의 의존성으로 전환

먼저 TanStack Router의 의존성을 설치합니다. 자세한 설치 지침은 TanStack Router 설치 방법 가이드를 참고합니다.

npm install @tanstack/react-router @tanstack/router-devtools

그런 다음 React Location 의존성을 제거합니다.

npm uninstall @tanstack/react-location @tanstack/react-location-devtools

2단계: 파일 기반 라우팅 watcher 사용

프로젝트에서 Vite(또는 지원되는 bundler 중 하나)를 사용한다면 TanStack Router 플러그인을 사용해 라우트 파일의 변경 사항을 감시하고 라우트 구성을 자동으로 업데이트할 수 있습니다.

Vite 플러그인을 설치합니다.

npm install -D @tanstack/router-plugin

그리고 vite.config.js에 추가합니다.

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { tanstackRouter } from '@tanstack/router-plugin/vite'

export default defineConfig({
  // ...
  plugins: [tanstackRouter(), react()],
})

그러나 애플리케이션에서 Vite를 사용하지 않는 경우에는 다른 지원되는 bundler를 사용하거나, @tanstack/router-cli 패키지를 사용해 라우트 파일의 변경 사항을 감시하고 라우트 구성을 자동으로 업데이트할 수 있습니다.

3단계: 프로젝트에 파일 기반 구성 파일 추가

프로젝트 루트에 다음 내용으로 tsr.config.json 파일을 만듭니다.

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

tsr.config.json 파일의 전체 옵션 목록은 파일 기반 라우팅 가이드에서 확인할 수 있습니다.

4단계: routes 디렉터리 만들기

프로젝트의 src 디렉터리에 routes 디렉터리를 만듭니다.

mkdir src/routes

5단계: 루트 라우트 파일 만들기

// src/routes/__root.tsx
import { createRootRoute, Outlet, Link } from '@tanstack/react-router'
import { TanStackRouterDevtools } from '@tanstack/router-devtools'

export const Route = createRootRoute({
  component: () => {
    return (
      <>
        <div>
          <Link to="/" activeOptions={{ exact: true }}>
            Home
          </Link>
          <Link to="/posts">Posts</Link>
        </div>
        <hr />
        <Outlet />
        <TanStackRouterDevtools />
      </>
    )
  },
})

6단계: 인덱스 라우트 파일 만들기

// src/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: Index,
})

인덱스 라우트에 필요한 관련 컴포넌트와 로직을 src/index.tsx 파일에서 src/routes/index.tsx 파일로 옮겨야 합니다.

7단계: posts 라우트 파일 만들기

// src/routes/posts.tsx
import { createFileRoute, Link, Outlet } from '@tanstack/react-router'

export const Route = createFileRoute('/posts')({
  component: Posts,
  loader: async () => {
    const posts = await fetchPosts()
    return {
      posts,
    }
  },
})

function Posts() {
  const { posts } = Route.useLoaderData()
  return (
    <div>
      <nav>
        {posts.map((post) => (
          <Link
            key={post.id}
            to={`/posts/$postId`}
            params={{ postId: post.id }}
          >
            {post.title}
          </Link>
        ))}
      </nav>
      <Outlet />
    </div>
  )
}

posts 라우트에 필요한 관련 컴포넌트와 로직을 src/index.tsx 파일에서 src/routes/posts.tsx 파일로 옮겨야 합니다.

8단계: posts 인덱스 라우트 파일 만들기

// src/routes/posts.index.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/posts/')({
  component: PostsIndex,
})

posts 인덱스 라우트에 필요한 관련 컴포넌트와 로직을 src/index.tsx 파일에서 src/routes/posts.index.tsx 파일로 옮겨야 합니다.

9단계: posts ID 라우트 파일 만들기

// src/routes/posts.$postId.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/posts/$postId')({
  component: PostsId,
  loader: async ({ params: { postId } }) => {
    const post = await fetchPost(postId)
    return {
      post,
    }
  },
})

function PostsId() {
  const { post } = Route.useLoaderData()
  // ...
}

posts ID 라우트에 필요한 관련 컴포넌트와 로직을 src/index.tsx 파일에서 src/routes/posts.$postId.tsx 파일로 옮겨야 합니다.

10단계: 라우트 트리 생성

지원되는 bundler 중 하나를 사용한다면 dev 스크립트를 실행할 때 라우트 트리가 자동으로 생성됩니다.

지원되는 bundler를 사용하지 않는다면 다음 명령을 실행해 라우트 트리를 생성할 수 있습니다.

npx tsr generate

11단계: Router를 렌더링하도록 기본 진입 파일 업데이트

라우트 트리를 생성한 후 src/index.tsx 파일을 업데이트해 라우터 인스턴스를 만들고 렌더링할 수 있습니다.

// src/index.tsx
import React from 'react'
import ReactDOM from 'react-dom'
import { createRouter, RouterProvider } from '@tanstack/react-router'

// Import the generated route tree
import { routeTree } from './routeTree.gen'

// Create a new router instance
const router = createRouter({ routeTree })

// Register the router instance for type safety
declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

const domElementId = 'root' // Assuming you have a root element with the id 'root'

// Render the app
const rootElement = document.getElementById(domElementId)
if (!rootElement) {
  throw new Error(`Element with id ${domElementId} not found`)
}

ReactDOM.createRoot(rootElement).render(
  <React.StrictMode>
    <RouterProvider router={router} />
  </React.StrictMode>,
)

완료!

이제 파일 기반 라우팅을 사용해 애플리케이션을 React Location에서 TanStack Router로 성공적으로 마이그레이션했을 것입니다.

React Location에는 애플리케이션에서 사용하고 있을 수 있는 몇 가지 기능이 더 있습니다. 이러한 기능을 마이그레이션하는 데 도움이 되는 가이드는 다음과 같습니다.

• 검색 매개변수
• 데이터 로딩
• 히스토리 타입
• 와일드카드 / 스플랫 / 캐치올 라우트
• 인증된 라우트

TanStack Router에도 살펴볼 만한 몇 가지 기능이 더 있습니다.

• 라우터 Context
• 프리로딩
• 경로 없는 레이아웃 라우트
• 라우트 마스킹
• SSR
• ... 그 외에도 더 있습니다!

문제가 있거나 질문이 있다면 TanStack Discord에서 언제든지 도움을 요청할 수 있습니다.