TanStack Query v5 실전 가이드 | React Query 마이그레이션·무한 스크롤·SSR 패턴

설치
npm install @tanstack/react-query
# 개발 도구 (선택 — 쿼리 상태 시각화)
npm install @tanstack/react-query-devtools

QueryClient 설정 — 기본값 조정 포인트
// app/providers.tsx (Next.js App Router 기준)
'use client'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import { useState } from 'react'

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        // 5분 동안은 캐시를 신선하게 본다
        staleTime: 5 * 60 * 1000,
        // 가비지 컬렉션 시간 (v4의 cacheTime)
        gcTime: 10 * 60 * 1000,
        // 네트워크 재연결 시 자동 리페치 여부
        refetchOnWindowFocus: false,
        // 실패 시 재시도 횟수
        retry: 1,
      },
    },
  })
}

let browserQueryClient: QueryClient | undefined
function getQueryClient() {
  if (typeof window === 'undefined') return makeQueryClient()
  if (!browserQueryClient) browserQueryClient = makeQueryClient()
  return browserQueryClient
}

export function Providers({ children }: { children: React.ReactNode }) {
  const queryClient = getQueryClient()
  return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  )
}

useQuery 기본 패턴 (v5 시그니처)
import { useQuery } from '@tanstack/react-query'

// queryKey는 배열. 캐시 키로 쓰인다.
// 같은 key를 여러 컴포넌트에서 쓰면 캐시를 공유한다.
export function useUserProfile(userId: string) {
  return useQuery({
    queryKey: ['user', userId],
    queryFn: async () => {
      const res = await fetch(`/api/users/${userId}`)
      if (!res.ok) throw new Error('유저 정보를 가져오지 못했습니다')
      return res.json() as Promise<User>
    },
    staleTime: 10 * 60 * 1000, // 10분
    enabled: !!userId,           // userId 없으면 실행 안 함
  })
}

// 컴포넌트에서 사용
function UserProfile({ userId }: { userId: string }) {
  const { data, isPending, isError, error } = useUserProfile(userId)

  if (isPending) return <Skeleton />
  if (isError) return <ErrorBanner message={error.message} />

  return <div>{data.name}</div>
}

onSuccess 대체 — useEffect 분리
// v4 방식 (v5에서 동작 안 함)
useQuery({
  queryKey: ['user'],
  queryFn: fetchUser,
  onSuccess: (data) => showToast(`반갑습니다, ${data.name}`), // ❌ v5 제거됨
})

// v5 방식 — useEffect로 분리
const { data, isSuccess } = useQuery({
  queryKey: ['user'],
  queryFn: fetchUser,
})

useEffect(() => {
  if (isSuccess && data) {
    showToast(`반갑습니다, ${data.name}`)
  }
}, [isSuccess, data])

낙관적 업데이트 — useMutation + onMutate
import { useMutation, useQueryClient } from '@tanstack/react-query'

function useLikeMutation(postId: string) {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: (liked: boolean) =>
      fetch(`/api/posts/${postId}/like`, {
        method: 'POST',
        body: JSON.stringify({ liked }),
        headers: { 'Content-Type': 'application/json' },
      }).then(r => r.json()),

    onMutate: async (liked) => {
      // 진행 중인 리페치를 취소해 낙관적 업데이트가 덮이지 않게 한다
      await queryClient.cancelQueries({ queryKey: ['post', postId] })

      // 현재 캐시값을 저장 (실패 시 롤백용)
      const previous = queryClient.getQueryData<Post>(['post', postId])

      // 캐시를 먼저 업데이트 (UI가 즉시 반응)
      queryClient.setQueryData<Post>(['post', postId], (old) =>
        old ? { ...old, liked, likeCount: liked ? old.likeCount + 1 : old.likeCount - 1 } : old
      )

      return { previous }
    },

    onError: (err, _, context) => {
      // 실패하면 이전 값으로 롤백
      if (context?.previous) {
        queryClient.setQueryData(['post', postId], context.previous)
      }
    },

    onSettled: () => {
      // 성공·실패와 무관하게 최종 서버 상태로 동기화
      queryClient.invalidateQueries({ queryKey: ['post', postId] })
    },
  })
}

useInfiniteQuery — 커서 기반 페이지네이션
import { useInfiniteQuery } from '@tanstack/react-query'
import { useRef, useCallback, useEffect } from 'react'

function useInfinitePosts() {
  return useInfiniteQuery({
    queryKey: ['posts', 'infinite'],
    queryFn: ({ pageParam }) =>
      fetch(`/api/posts?cursor=${pageParam ?? ''}`).then(r => r.json()),
    initialPageParam: '',                    // v5 필수 — 초기 cursor 값
    getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
  })
}

function PostList() {
  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfinitePosts()

  // IntersectionObserver로 바닥 감지
  const sentinelRef = useRef<HTMLDivElement>(null)
  const handleIntersect = useCallback(
    (entries: IntersectionObserverEntry[]) => {
      if (entries[0].isIntersecting && hasNextPage && !isFetchingNextPage) {
        fetchNextPage()
      }
    },
    [hasNextPage, isFetchingNextPage, fetchNextPage]
  )

  useEffect(() => {
    const el = sentinelRef.current
    if (!el) return
    const observer = new IntersectionObserver(handleIntersect, { threshold: 0.1 })
    observer.observe(el)
    return () => observer.disconnect()
  }, [handleIntersect])

  const posts = data?.pages.flatMap((page) => page.items) ?? []

  return (
    <>
      {posts.map((post) => <PostCard key={post.id} post={post} />)}
      <div ref={sentinelRef} style={{ height: 1 }} />
      {isFetchingNextPage && <Spinner />}
    </>
  )
}

Server Component에서 prefetch — dehydrate/hydrate 패턴
// app/posts/page.tsx (Server Component)
import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query'
import { PostList } from './_components/PostList'

export default async function PostsPage() {
  const queryClient = new QueryClient()

  // 서버에서 미리 가져온다
  await queryClient.prefetchQuery({
    queryKey: ['posts'],
    queryFn: () => fetch('https://api.example.com/posts').then(r => r.json()),
  })

  return (
    // 서버 캐시를 클라이언트로 전달
    <HydrationBoundary state={dehydrate(queryClient)}>
      <PostList />
    </HydrationBoundary>
  )
}

// app/posts/_components/PostList.tsx (Client Component)
'use client'
import { useQuery } from '@tanstack/react-query'

export function PostList() {
  // 서버에서 prefetch한 데이터를 즉시 사용 (네트워크 요청 없음)
  const { data } = useQuery({
    queryKey: ['posts'],
    queryFn: () => fetch('/api/posts').then(r => r.json()),
  })

  return data?.map((post: Post) => <PostCard key={post.id} post={post} />)
}