TanStack Query v5 업데이트의 핵심 변경 사항과 안전한 마이그레이션을 위한 실전 가이드
"라이브러리 업데이트, 또 해야 해?"라고 생각하시나요?
프론트엔드 개발자에게 버전 업데이트는 숙명과도 같습니다.
하지만 이번 React Query v5는 단순한 기능 추가를 넘어,
라이브러리의 사이즈를 줄이고 사용성을 대폭 개선하는 '다이어트'와 '체질
개선'에 성공했습니다.
기존 사용자라면 반드시 알아야 할 핵심 변경점 3가지와
마이그레이션 전략을 아주 쉽게 정리해 드립니다.
📦 포인트 1: 이제는 '하나의 객체'로 통일됩니다
v5에서 가장 눈에 띄는 변화는
useQuery 훅의 사용법 통일입니다.
기존 v4까지는 인자를 넘기는 방식이 여러 가지여서 혼란스러웠지만, 이제는
단일 객체 형태만 지원합니다.
❌ v4 (더 이상 지원 안 함)
useQuery(key, fn, options)
useQuery(key, options)
// 인자 순서를 외워야 했습니다.
✅ v5 (권장 방식)
useQuery({
queryKey: key,
queryFn: fn,
...options
})
// 객체 하나로 깔끔해졌습니다!
💡 Tip: 이 변화 덕분에 타입 추론이 훨씬 강력해졌으며,
코드의 가독성이 크게 향상되었습니다.
🚫 포인트 2: useQuery에서 콜백이 사라졌습니다
아마 가장 충격적인 변화일 수 있습니다.
onSuccess, onError, onSettled 콜백이
useQuery 옵션에서 삭제되었습니다.
이 콜백들은 상태 동기화 버그를 자주 일으켰으며, React의 선언적 패턴과 맞지 않았기 때문입니다.
예를 들어, 컴포넌트가 리렌더링될 때 콜백 실행 예측이 어려웠던 문제를 해결하기 위함입니다.
🔄 어떻게 대체하나요?
| 상황 | 대체 방법 |
|---|---|
| 데이터 패칭 성공 후 Toast 띄우기 |
useEffect 활용 또는 상태(status) 확인
|
| 에러 발생 시 처리 | Error Boundaries 사용 권장 |
✨ 포인트 3: 더욱 강력해진 Suspense와 InfiniteQuery
v5에서는 React 18의 기능인 Suspense를 완벽하게 지원하기
위해 전용 훅이 등장했습니다.
또한 무한 스크롤 구현이 획기적으로 간소화되었습니다.
-
1. useSuspenseQuery
데이터가 로딩 중일 때는 컴포넌트를 렌더링하지 않고 상위 Suspense로 위임합니다.
isLoading상태를 따로 관리할 필요가 없어 코드가 매우 깔끔해집니다.
-
2. Simplified InfiniteQuery
이제initialPageParam값을 필수로 명시해야 합니다.
이로 인해 `undefined`로 인한 예기치 않은 오류를 방지할 수 있습니다.
🛠️ 마이그레이션 실전 가이드
v5로 넘어갈 준비가 되셨나요? 수동으로 모든 코드를 고치는 것은 너무 힘든
일입니다.
TanStack 팀에서 제공하는 Codemod를 활용하면 작업 시간을
획기적으로 줄일 수 있습니다.
💻 터미널 명령어 (Codemod)
npx jscodeshift ./path/to/src/ \
-t ./node_modules/@tanstack/react-query/codemods/v5/remove-overloads/remove-overloads.js
위 명령어를 실행하면 객체 인자 형태로 자동 변환해 줍니다.
반드시 Git 커밋을 한 후 실행하세요!
🚀 요약 및 다음 단계
React Query v5는 개발자의 실수를 줄이고, React 최신 스펙에 맞춘
더 단단한 라이브러리로 진화했습니다.
초기 마이그레이션 비용은 들지만, 장기적으로 유지보수하기 훨씬 좋은 코드가
될 것입니다.
- 객체형 인자 사용 습관화하기.
- onSuccess 대신 useEffect나 Action 활용하기.
- Codemod로 빠르게 문법 변환하기.
지금 바로 여러분의 프로젝트에서
npm install @tanstack/react-query@latest를 실행해 보세요!
댓글 쓰기