서버 상태와 클라이언트 상태의 분리 — TanStack Query v5 완벽 가이드
애플리케이션 상태의 대부분은 사실 서버에서 온 데이터의 캐시입니다. TanStack Query v5의 useQuery와 useMutation, staleTime·gcTime, 낙관적 업데이트, useSuspenseQuery와 React 19까지 정리한 완벽 가이드.
서버 상태와 클라이언트 상태의 분리 — TanStack Query v5 완벽 가이드
개요: 전역 상태 라이브러리가 줄어든 이유
몇 년 전만 해도 React 앱의 표준 구성은 “전역 상태 라이브러리 + 컴포넌트”였습니다. 서버에서 온 데이터도 결국 스토어에 담아야 했으니까요. API 호출은 thunk나 saga로 감싸고, 로딩 플래그와 에러 객체를 스토어에 넣고, 어느 화면에서 데이터를 다시 받을지 직접 조율했습니다. 그런데 돌아보면 그 데이터의 대부분은 소유권이 서버에 있는 값이었습니다. 클라이언트는 캐시를 들고 있었을 뿐이고요.
TanStack Query의 메인테이너 TkDodo가 Practical React Query에서 대중화한 구분이 바로 이것입니다. 클라이언트 상태는 모달 열림 여부나 테마처럼 우리가 소유하고 즉시 바꾸는 값이고, 서버 상태는 다른 곳에 진실(source of truth)이 있고 우리가 보는 것은 언제든 바뀔 수 있는 스냅샷입니다. 서버 상태를 잘 다루려면 신선도 관리, 중복 요청 제거, 재시도, 캐시 무효화 같은 캐시 설계가 필요한데, 이건 전역 상태 라이브러리가 원래 하던 일이 아니었습니다. 전역 상태 라이브러리가 줄어들었다는 감각의 실체는 “서버 상태가 전용 도구로 분리된 것”입니다.
TanStack Query v5는 2023년 10월 17일에 발표됐고, 이 글은 v5 공식 문서 기준으로 정리했습니다. 기본기인 비동기 처리 자체에 대해선 예전의 자바스크립트 비동기 처리 정리 글을 참고하셔도 좋습니다.
핵심 개념: 두 상태는 무엇이 다른가
| 구분 | 클라이언트 상태 | 서버 상태 |
|---|---|---|
| 진실의 위치 | 클라이언트 | 서버(언제든 바뀔 수 있음) |
| 갱신 주체 | 사용자 조작 | 서버, 다른 사용자, 동기화 |
| 필요한 관심사 | 단순 읽기/쓰기 | 신선도, 캐싱, 재시도, 동기화 |
| 대표 예시 | 모달, 테마, 폼 임시값 | 사용자 프로필, 게시글 목록 |
이 표에서 뒤쪽 열의 요구사항을 전부 라이브러리에 맡기는 순간, 남는 클라이언트 상태는 생각보다 작다는 걸 경험하게 됩니다.
설치와 기본 세팅
npm i @tanstack/react-query
QueryClient를 만들고 프로바이더로 감싸는 것이 전부입니다. 공식 설치 문서 기준으로 React 18 이상과 호환됩니다.
// app/providers.tsx
'use client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { useState } from 'react';
export function Providers({ children }: { children: React.ReactNode }) {
const [queryClient] = useState(
() =>
new QueryClient({
defaultOptions: {
queries: {
staleTime: 60_000,
},
},
}),
);
return (
<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
);
}
useState로 감싸 렌더링마다 클라이언트가 새로 만들어지지 않게 하는 패턴을 씁니다.
useQuery: 선언적인 서버 상태
import { useQuery } from '@tanstack/react-query';
function PostList({ userId }: { userId: string }) {
const { data, isPending, isError, error } = useQuery({
queryKey: ['posts', userId],
queryFn: () => fetchPosts(userId),
staleTime: 30_000,
});
if (isPending) return <p>불러오는 중…</p>;
if (isError) return <p>에러: {error.message}</p>;
return <ul>{data.map((post) => <li key={post.id}>{post.title}</li>)}</ul>;
}
v5에서 눈에 띄는 변화 두 가지입니다.
- 인자는 객체 하나뿐입니다. v4까지 있던 위치 인자 오버로드가 제거되었습니다.
- 로딩 판별은
isLoading대신isPending입니다. 캐시된 데이터가 있는 재요청 중에도isPending은 거짓이므로, 기존 데이터를 보여 주며 배경에서 갱신하는 UI를 만들기 쉽습니다.
queryKey는 직렬화 가능한 값이면 무엇이든 되고, 키가 곧 의존성 역할을 합니다. userId가 바뀌면 다른 키로 취급되어 자동으로 새로 가져옵니다. useQuery의 모든 옵션은 공식 레퍼런스에 정리되어 있습니다.
staleTime과 gcTime: 두 개의 시계
TanStack Query를 이해하는 열쇠는 시계가 두 개라는 점입니다. Important Defaults 문서를 기준으로 정리하면 다음과 같습니다.
- staleTime (기본 0): 데이터가 신선하다고 보는 시간. 0이므로 받자마자 stale가 되고, 새 마운트·윈도우 포커스·네트워크 복구 때 자동으로 다시 가져옵니다.
- gcTime (기본 5분): 사용 중이지 않은 캐시가 메모리에 남는 시간. v4의
cacheTime이 v5에서 개명된 이름입니다.
예를 들어 목록 화면을 나갔다가 10초 뒤 다시 들어가면, 5분이 지나지 않았으므로 캐시된 데이터를 즉시 보여 주고(화면 깜빡임 없음), 그 데이터는 이미 stale이므로 배경에서 최신 데이터를 가져와 갱신합니다. “캐시 히트”와 “재검증”이 분리되어 있는 것입니다.
그 외 기본값도 적극적입니다. 실패한 쿼리는 기본 3회 지수 백오프로 재시도하고, refetchOnWindowFocus가 켜져 있어 탭으로 돌아오면 재검증합니다. 이 기본값들이 처음엔 공격적으로 느껴질 수 있지만, 서버 상태의 목표가 “화면에 최신 상태 유지”임을 생각하면 합리적입니다. 다만 staleTime을 0으로 두면 불필요한 요청이 늘 수 있으니, 도메인별로 현실적인 값을 지정하는 것이 첫 튜닝 포인트입니다.
useMutation과 쿼리 무효화
데이터를 바꾸는 작업은 useMutation으로 선언합니다.
import { useMutation, useQueryClient } from '@tanstack/react-query';
function useAddPost() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: (input: AddPostInput) => createPost(input),
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['posts'] });
},
});
}
핵심은 성공 후의 invalidateQueries입니다. 무효화는 캐시를 지우는 게 아니라 stale로 마킹하는 작업이고, 화면에 마운트되어 있는(active) 쿼리는 즉시 다시 가져옵니다. 키는 접두사로 매칭되므로 ['posts']를 무효화하면 ['posts', userId]도 함께 무효화됩니다. mutation 후 관련 목록 전체를 갱신하는 이 패턴이 가장 무난한 기본형이고, 자세한 규칙은 쿼리 무효화 가이드에 있습니다.
낙관적 업데이트: onMutate에서 rollback까지
좋아요 버튼을 눌렀을 때 서버 응답을 기다렸다가 UI를 바꾸면 반 박자 느립니다. 낙관적 업데이트는 요청 성공을 가정하고 캐시를 먼저 바꾸고, 실패하면 되돌리는 패턴입니다. 공식 낙관적 업데이트 가이드의 구조를 좋아요 예시로 옮기면 다음과 같습니다.
function useLikePost(postId: number) {
const queryClient = useQueryClient();
return useMutation({
mutationFn: () => api.like(postId),
// 1) 요청 전: 캐시를 낙관적으로 바꾼다
onMutate: async () => {
await queryClient.cancelQueries({ queryKey: ['posts'] });
const previous = queryClient.getQueryData(['posts']);
queryClient.setQueryData(['posts'], (old) =>
old ? applyLike(old, postId) : old,
);
return { previous }; // 롤백용 스냅샷
},
// 2) 실패: 스냅샷으로 되돌린다
onError: (_error, _variables, context) => {
queryClient.setQueryData(['posts'], context?.previous);
},
// 3) 성공/실패 무관: 최종적으로 서버 상태와 동기화
onSettled: () => {
queryClient.invalidateQueries({ queryKey: ['posts'] });
},
});
}
순서를 정리하면 onMutate(낙관적 반영 + 롤백 스냅샷 반환) → 요청 → 실패 시 onError에서 스냅샷 복구 → onSettled에서 무효화, 입니다. 진행 중인 쿼리 재요청을 취소하는 cancelQueries를 맨 처음 호출하는 것도 중요합니다. 취소하지 않으면 낙관적 값이 이전 데이터로 덮여 버릴 수 있습니다.
useSuspenseQuery와 React 19
로딩 분기(isPending) 코드가 반복적으로 느껴진다면 Suspense 통합을 고려할 수 있습니다.
import { useSuspenseQuery } from '@tanstack/react-query';
function PostDetail({ postId }: { postId: number }) {
const { data } = useSuspenseQuery({
queryKey: ['post', postId],
queryFn: () => fetchPost(postId),
});
return <article>{data.title}</article>;
}
useSuspenseQuery는 데이터가 준비될 때까지 렌더링을 중단하고 가장 가까운 Suspense 경계를 띄웁니다. data가 옵셔널하지 않아 분기 없이 쓸 수 있고, 에러는 ErrorBoundary로 흐릅니다. 자세한 내용은 Suspense 가이드에 정리되어 있습니다.
React 19와의 궁합도 좋아지고 있습니다. v5.59.0(2024년 10월 1일)부터 React의 use() 훅과 함께 쓰는 통합이 실험적으로 추가됐고, React 19 자체는 2024년 12월 5일 정식 출시된 상태입니다. Suspense를 둘러싼 동시성 렌더링의 배경은 React 동시성 렌더링 이해하기에서 다룬 적이 있으니 참고하세요.
그래도 전역 상태가 필요한 순간
서버 상태를 TanStack Query로 보내고 나면, 남는 클라이언트 상태는 대개 두 종류입니다.
- UI 상태: 열려 있는 모달, 사이드바 접힘 여부, 테마 — 지역 상태나 Context로 충분한 경우가 많습니다.
- 여러 화면을 잇는 폼 임시값: 작성 중인 게시글 초안처럼 서버로 아직 보내지 않은 값.
TkDodo는 React Query as a State Manager에서 캐시 자체를 파생 상태의 원천으로 쓰는 방법을 다룹니다. 요점은 “전역 상태 라이브러리가 사라진 것이 아니라, 서버 상태라는 큰 짐이 옮겨가면서 원래 목적만 남게 되었다”는 것입니다. 이 관점을 유지하면 상태 관리 선택이 훨씬 단순해집니다.
정리
- 상태를 소유권 기준으로 나누면 문제의 대부분은 서버 상태, 즉 캐시 관리였습니다.
useQuery는 요청을 선언하고,queryKey가 의존성이며,staleTime/gcTime두 시계가 재검증과 보관을 나눠 담당합니다.- 변경은
useMutation+invalidateQueries가 기본형이고, 반응 속도가 중요하면onMutate→onError롤백 →onSettled동기화의 낙관적 업데이트를 얹습니다. - 로딩 분기가 피곤해지면
useSuspenseQuery로 Suspense에 위임하고, React 19와의 통합도 이미 진행 중입니다.
새 프로젝트를 시작할 때 이제 “전역 상태 라이브러리를 뭘 쓸까”보다 “서버 상태를 어떻게 다룰까”부터 정하는 것이 자연스러운 흐름이 됐습니다. 이 글의 패턴들이 그 첫 삽이 되길 바랍니다.
레퍼런스
- Announcing TanStack Query v5 — 2023-10-17 v5 발표 글
- Installation (TanStack Query 문서) — 설치와 호환 환경
- Important Defaults — staleTime·gcTime 등 기본값 동작
- useQuery 레퍼런스 — 옵션과 반환값 전체
- useMutation 레퍼런스 — mutation 옵션과 콜백
- Query Invalidation 가이드 — 무효화 매칭 규칙
- Optimistic Updates 가이드 — onMutate/rollback 공식 패턴
- Suspense 가이드 — useSuspenseQuery 계열 훅
- Release v5.59.0 (TanStack/query) — 2024-10-01, React
use()지원 추가 - Practical React Query (TkDodo) — 클라이언트 상태 vs 서버 상태 구분
- React Query as a State Manager (TkDodo) — 캐시를 상태 원천으로 쓰는 관점
- React v19 — React 19 정식 출시 안내