💡 핵심 요약

React 전용 라이브러리에서 프레임워크 범용 생태계(TanStack)로 확장되었습니다. v5는 문법의 단일화(객체 형태 강제), 콜백 옵션 제거, 네이밍 개선, Suspense 전용 훅 추가를 통해 타입스크립트 친화성과 예측 가능성을 대폭 향상시켰습니다.

1. 📦 패키지 및 기본 구조

2. ⚙️ 문법의 통일: Single Object Signature

더 이상 훅의 인자로 문자열, 콜백 함수, 옵션을 섞어서 쓸 수 없습니다. 오직 단일 객체(Object) 형태로만 전달해야 합니다.

TypeScript

`// ❌ v3 (v5에서는 에러 발생) useQuery('todos', fetchTodos, { enabled: true });

// ✅ v5 (단일 객체 형태로 통일) useQuery({ queryKey: ['todos'], queryFn: fetchTodos, enabled: true, });`

3. 🚨 useQuery 콜백 함수 완전 제거 (가장 큰 변화)

⚠️ useQuery 내부에 있던 onSuccess, onError, onSettled 옵션이 완전히 제거되었습니다. (단, useMutation에는 그대로 유지됩니다.)

• 제거된 이유: 상태 동기화 문제와 불필요한 렌더링 사이클 버그를 방지하기 위함입니다.
• 대안 / 마이그레이션 방법:
  • 데이터 가공이 필요할 때: select 옵션 사용
  • 부수 효과(Toast 알림 등)가 필요할 때: 컴포넌트 레벨에서 useEffect를 사용하거나, 전역 QueryCache / MutationCache 단에서 처리

4. 🏷️ 직관적인 네이밍 변경

• cacheTime ➡️ gcTime
  • 캐시 유지 시간으로 오해하는 것을 방지하기 위해, 안 쓰는 데이터가 가비지 컬렉터(GC)에 수거되기까지의 시간이라는 의미로 변경되었습니다.
• status === 'loading' ➡️ status === 'pending'
  • 캐시된 데이터조차 없는 완전 초기 상태를 Pending으로 부릅니다. (isPending 플래그 사용)
  • v5에서 isLoading은 isFetching && isPending 상태를 의미하는 것으로 좁혀졌습니다.

5. 🚀 React 18 Suspense 전용 훅 도입

기존의 { suspense: true } 옵션을 제거하고, 타입 안정성이 보장되는 별도의 훅으로 분리되었습니다. 해당 훅을 사용하면 반환되는 data가 undefined가 아님을 타입스크립트가 보장합니다.

• useSuspenseQuery
• useSuspenseInfiniteQuery