React Query v4에서 v5로의 현실적인 마이그레이션 전략

React Query v5가 출시되면서 많은 개발자들이 마이그레이션을 고민하고 있습니다. 이 글에서는 v4에서 v5로 효과적으로 전환할 수 있는 현실적인 방안을 살펴보겠습니다.

마이그레이션 준비

1. 의존성 업데이트

먼저 package.json 파일에서 @tanstack/react-query 패키지를 최신 v5 버전으로 업데이트합니다.

npm install @tanstack/react-query@latest

2. 최소 요구사항 확인

React Query v5는 다음과 같은 최소 요구사항이 있습니다:

• TypeScript v4.7 이상
• React v18.0 이상

프로젝트의 의존성이 이를 충족하는지 확인하고, 필요하다면 업데이트합니다.

주요 변경사항 적용

1. 단일 객체 시그니처로 통일

v5에서 가장 큰 변화는 useQuery, useMutation 등의 훅이 단일 객체 시그니처만을 지원한다는 점입니다.

// v4
const query = useQuery(['todos'], fetchTodos);

// v5
const query = useQuery({ 
  queryKey: ['todos'], 
  queryFn: fetchTodos 
});

2. cacheTime을 gcTime으로 변경

캐시 관련 옵션명이 변경되었습니다.

// v4
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      cacheTime: 1000 * 60 * 10,
    },
  },
});

// v5
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 60 * 10,
    },
  },
});

3. 무한 쿼리의 defaultPageParam 필수화

무한 쿼리 사용 시 defaultPageParam을 명시적으로 설정해야 합니다.

// v5
const query = useInfiniteQuery({
  queryKey: ['projects'],
  queryFn: fetchProjects,
  initialPageParam: 0,
  getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
});

점진적 마이그레이션 전략

대규모 프로젝트의 경우, 한 번에 모든 코드를 변경하는 것은 현실적으로 어려울 수 있습니다. 다음과 같은 점진적 접근 방식을 고려해보세요.

1. 코드모드 활용

TanStack Query v5는 자동 마이그레이션을 위한 코드모드를 제공합니다. 이를 활용하여 기본적인 변경사항을 자동으로 적용할 수 있습니다.

npx jscodeshift@latest ./src \
  --extensions=ts,tsx \
  --parser=tsx \
  --transform=./node_modules/@tanstack/react-query/build/codemods/src/v5/remove-overloads/remove-overloads.js

2. ESLint 규칙 활용

TanStack Query의 ESLint 플러그인을 사용하여 v5 스타일 가이드를 적용하고, 점진적으로 코드를 수정할 수 있습니다.

{
  "extends": [
    "plugin:@tanstack/eslint-plugin-query/recommended"
  ]
}

3. 새 기능은 v5 스타일로 개발

새로운 기능을 개발할 때는 v5 스타일을 따르고, 기존 코드는 점진적으로 리팩토링합니다.

4. 테스트 커버리지 확대

마이그레이션 과정에서 예기치 않은 버그를 방지하기 위해 테스트 커버리지를 확대합니다. 특히 쿼리 로직과 관련된 부분에 집중하여 테스트를 작성합니다.

주의사항 및 팁

1. 타입 체크 활용: TypeScript를 사용 중이라면, 타입 체크를 통해 마이그레이션 과정에서 발생할 수 있는 오류를 사전에 파악할 수 있습니다.
2. 성능 모니터링: 마이그레이션 후 애플리케이션의 성능을 모니터링하여 예기치 않은 성능 저하가 없는지 확인합니다.
3. 문서화: 마이그레이션 과정과 주요 변경사항을 문서화하여 팀 내 지식 공유를 촉진합니다.
4. 단계적 롤아웃: 가능하다면 일부 기능 또는 페이지부터 v5를 적용하고 점진적으로 확대합니다.
5. 커뮤니티 활용: TanStack Query 커뮤니티와 GitHub 이슈를 활용하여 마이그레이션 중 발생하는 문제에 대한 해결책을 찾습니다.

결론

React Query v4에서 v5로의 마이그레이션은 도전적일 수 있지만, 체계적인 접근과 점진적인 전략을 통해 성공적으로 수행할 수 있습니다. 코드모드, ESLint 규칙, 그리고 점진적 리팩토링을 조합하여 사용하면 효율적인 마이그레이션이 가능합니다. 또한, 이 과정을 통해 코드베이스를 현대화하고 새로운 기능을 활용할 수 있는 기회로 삼을 수 있습니다.