TanStack Query vs Zustand: 서버 상태와 클라이언트 상태 차이

서버 상태란 무엇인가

서버 상태는 브라우저가 소유하는 값이 아니라 서버나 API가 원본을 가지고 있는 데이터입니다.

예를 들어 TaskFlow의 작업 목록을 다음 API에서 가져온다고 가정합니다.

GET /api/tasks

이 데이터에는 단순한 값 저장 이상의 문제가 따라옵니다.

• 언제 요청해야 하는가
• 요청 중인가
• 실패했는가
• 이전 결과를 재사용할 수 있는가
• 언제 다시 가져와야 하는가
• 저장 후 어떤 목록을 갱신해야 하는가
• 여러 컴포넌트가 같은 요청을 사용할 때 어떻게 캐시할 것인가

TanStack Query는 이런 서버 상태의 조회·캐시·동기화를 관리합니다.

Zustand가 맡는 상태

Zustand는 서버 원본을 저장하는 도구라기보다 클라이언트 전역 상태를 관리하는 데 적합합니다.

selectedTaskId
isTaskModalOpen
sidebarOpen
사용자 UI 설정
클라이언트 필터 상태

이 값들은 서버에서 가져온 원본 데이터가 아니라 UI 동작과 선택 상태입니다.

React state가 맡는 상태

한 컴포넌트 안에서만 사용하는 값은 로컬 state가 더 단순합니다.

const [title, setTitle] = useState('');

TaskForm의 입력 중인 문자열처럼 다른 화면이 알 필요가 없는 값은 굳이 TanStack Query나 Zustand에 넣지 않습니다.

역할을 한 줄로 구분하기

API 원본 데이터와 서버 동기화
→ TanStack Query


여러 컴포넌트가 공유하는 클라이언트 UI 상태
→ Zustand


한 컴포넌트 내부의 임시 상태
→ React state

Query 캐시와 Next.js 캐시는 다릅니다

TanStack Query의 QueryClient 캐시는 클라이언트 애플리케이션이 queryKey를 기준으로 서버 상태를 관리하는 캐시입니다.

Next.js의 서버 측 캐싱은 Server Component, fetch, Cache Components, revalidation 등 서버 렌더링 계층의 문제입니다.

둘 다 “캐시”라는 단어를 사용하지만 같은 저장소가 아닙니다.

이 차이는 마지막 15회차에서 다시 정리합니다.

TanStack Query 학습 순서

서버 상태 경계 결정
→ TanStack Query 설치
→ QueryClientProvider
→ 첫 useQuery
→ queryFn 분리
→ queryKey 설계
→ staleTime / gcTime
→ useMutation
→ invalidateQueries / setQueryData
→ pagination
→ useInfiniteQuery
→ optimistic update / rollback
→ 목록·상세 캐시 동기화
→ 서버 prefetch
→ HydrationBoundary
→ Next.js cache와 Query cache 경계

이 과정의 기존 예제는 TanStack Query v5 객체 문법을 기준으로 합니다. 실제 설치와 실행에서는 각 실습의 package-lock.json에 고정된 버전을 사용합니다.

자주 하는 실수

API 응답을 Zustand에 다시 복사합니다

TanStack Query cache
→ tasks


Zustand
→ 같은 tasks 복사

이렇게 두 원본을 만들면 mutation 이후 어느 값을 갱신해야 하는지 불명확해집니다.

모든 fetch를 TanStack Query로 바꿉니다

Server Component에서 서버 렌더링만 필요한 데이터까지 반드시 useQuery로 바꿀 필요는 없습니다.

TanStack Query는 클라이언트에서 서버 상태를 캐시·재요청·변경해야 할 때 특히 유용합니다.

loading을 별도 useState로 다시 만듭니다

useQuery가 이미 pending/error/success 상태를 제공합니다. 같은 상태를 별도로 복제하지 않습니다.

학습 완료 체크리스트

• 서버 상태와 클라이언트 상태를 구분할 수 있습니다.
• TanStack Query와 Zustand의 역할을 설명할 수 있습니다.
• Query 캐시와 Next.js 서버 캐시가 같은 개념이 아님을 이해했습니다.
• 서버가 원본인 목록과 브라우저가 원본인 UI 상태의 소유자를 구분할 수 있습니다.

# 원본 소유권

서버의 /api/tasks가 tasks 원본입니다. 클라이언트 응답 캐시는 Query가 관리합니다. 선택 ID·필터 UI는 React state, 입력 문자열은 TaskForm입니다. Zustand에 같은 tasks를 다시 복사하지 않습니다.

next-step-17-route-handler

next-step-17-route-handler

GET /api/tasks
POST /api/tasks
Server Component / Client Component 경계

/tasks API 원본
→ TanStack Query


selectedTaskId
modal
UI 설정
→ Zustand 또는 React state


TaskForm 입력 문자열
→ React local state

fetch 결과와 UI 상태의 책임이 명확히 분리되지 않음

서버 원본 / 클라이언트 전역 / 로컬 상태
세 영역의 소유자를 먼저 결정

→ 1. 서버 상태 경계
○ 2. Provider + useQuery
○ 3. queryFn
○ 4. queryKey
○ 5. 캐시 수명
○ 6~11. mutation·동기화·복구
○ 12~15. SSR·Hydration·캐시 경계

query-step-01-boundary

다음 학습

다음 글에서는 TanStack Query를 실제 설치하고 QueryClientProvider와 첫 useQuery를 연결합니다.

다음 글: TanStack Query Provider와 첫 useQuery 상태 처리 실습 가이드

공식 문서

• TanStack Query: https://tanstack.com/query/latest
• Quick Start: https://tanstack.com/query/latest/docs/framework/react/quick-start

글 소개·학습 준비·전체 목차

TanStack Query · 1 / 15 · 필수 길잡이 · 서버 상태 경계

TanStack Query를 처음 배울 때 가장 중요한 것은 useQuery 문법을 외우는 것이 아니라, 어떤 데이터를 TanStack Query가 맡아야 하는지 구분하는 것입니다.

상단은 서버 데이터와 UI 상태의 소유권을 정하는 독립 설계 실습입니다. 하단의 누적 프로젝트 경로는 Next.js TaskFlow의 Route Handler를 기반으로 조회·캐시·변경·SSR/Hydration을 확장합니다.

상단에서는 이 글만 찾아온 독자도 TanStack Query와 Zustand의 역할 차이를 이해할 수 있게 설명하고, 하단에서는 TaskFlow의 서버 상태 경계를 정리합니다.

이번 글에서 배우는 내용

• 서버 상태와 클라이언트 상태의 차이
• TanStack Query가 해결하는 문제
• Zustand가 맡는 상태
• React 로컬 state가 맡는 상태
• Next.js 서버 캐시와 Query 캐시가 다른 이유
• TaskFlow 15회 학습 흐름

먼저 알아야 할 내용

상단의 상태 소유권 실습은 설치 없이 진행하며 React 컴포넌트와 state의 역할만 알면 됩니다. 아래 기술 목록 중 Next.js App Router·서버/클라이언트 컴포넌트·Route Handler는 하단 누적 프로젝트를 이어 만들 때 필요한 지식입니다.

• React 컴포넌트와 state
• Next.js App Router
• Server Component와 Client Component
• Route Handler
• fetch 기본 사용법
• TypeScript 기본 타입

목차