Next.js 캐시와 TanStack Query 캐시 차이: 서버·클라이언트 경계 설계

TanStack Query cache

TanStack Query cache는 QueryClient가 관리합니다.

queryKey
queryFn 결과
staleTime
gcTime
mutation
invalidateQueries
setQueryData

브라우저에서 서버 데이터를 재사용하고, background refetch와 mutation 이후 동기화를 다루는 것이 핵심입니다.

Next.js 서버 캐시

Next.js 16에서 Cache Components를 활성화하면 async function이나 component에 use cache를 적용해 서버 결과를 캐시할 수 있습니다.

export async function getPublicTasks() {
  'use cache';


  return taskRepository.list();
}

cacheLife와 cacheTag를 함께 사용할 수도 있습니다.

import {
  cacheLife,
  cacheTag,
} from 'next/cache';


export async function getPublicTasks() {
  'use cache';


  cacheLife('minutes');
  cacheTag('tasks');


  return taskRepository.list();
}

이 cache는 QueryClient cache와 별개입니다.

Cache Components를 사용하지 않는 경우

현재 Next.js 문서의 previous model에서도 fetch 요청은 기본적으로 캐시되지 않습니다.

명시적으로 서버 fetch를 캐시하려면 다음처럼 설정할 수 있습니다.

fetch(url, {
  cache: 'force-cache',
});

또는 프로젝트 버전과 캐시 모델에 맞는 revalidation 설정을 사용합니다.

중요한 것은 “Next.js fetch는 항상 자동 캐시된다”라는 오래된 전제를 사용하지 않는 것입니다.

두 캐시 비교

Next.js server cache
- 서버 계층
- 여러 요청에서 재사용 가능
- Server Component / cached function 결과와 연결
- use cache, cacheLife, cacheTag
- revalidatePath / revalidateTag / updateTag 등


TanStack Query cache
- QueryClient 계층
- queryKey 기반 서버 상태
- 브라우저 상호작용에 강함
- staleTime / gcTime
- invalidateQueries / setQueryData
- mutation / optimistic update

invalidateQueries

브라우저 Query cache를 stale 처리하고 다시 서버 데이터를 확인하게 합니다.

queryClient.invalidateQueries({
  queryKey:
    taskKeys.lists(),
});

이 코드는 Next.js 서버 cache를 직접 무효화하지 않습니다.

revalidatePath

revalidatePath는 서버 환경에서 특정 Next.js path의 cached data를 무효화하는 API입니다.

import {
  revalidatePath,
} from 'next/cache';


revalidatePath('/tasks');

Client Component에서 호출하는 API가 아니며, QueryClient cache를 직접 바꾸지 않습니다.

양쪽 cache를 모두 사용하는 경우

예를 들어 공개 작업 통계는 Next.js 서버 cache를 사용하고, 로그인 사용자의 Task 목록은 TanStack Query가 관리한다고 가정할 수 있습니다.

mutation 후 어떤 데이터가 영향을 받는지에 따라 무효화 대상을 정합니다.

브라우저 Task 목록만 영향
→ invalidateQueries


서버에서 cache한 /tasks 결과도 영향
→ 서버 mutation 경로에서 revalidatePath / tag 처리
→ 브라우저에서는 invalidateQueries


둘 다 영향
→ 각 계층을 각각 무효화

한 API 호출로 모든 캐시가 자동으로 서로 동기화된다고 가정하지 않습니다.

중복 캐시를 줄이는 기준

같은 데이터에 여러 캐시 계층을 붙이면 정책도 늘어납니다.

다음 질문을 먼저 합니다.

1. 이 데이터는 서버에서 여러 요청 간 재사용해야 하는가?
2. 브라우저에서 refetch·mutation·optimistic update가 필요한가?
3. SSR 초기 데이터만 필요하고 이후 상호작용은 적은가?
4. 사용자별 민감 데이터인가?
5. 캐시가 오래될 때 누가 무효화하는가?

추천 역할 패턴

서버 렌더 중심 공개 데이터

Server Component
+ Next.js use cache
+ 필요 시 revalidateTag/revalidatePath

Client Query가 필요하지 않을 수 있습니다.

사용자 상호작용이 많은 서버 데이터

TanStack Query
+ mutation
+ invalidateQueries
+ optimistic update

초기 SSR이 필요하면 Server prefetch + HydrationBoundary를 추가합니다.

클라이언트 UI 상태

Zustand 또는 React state

Query cache에 modal, selectedTaskId 같은 UI state를 넣지 않습니다.

서버 데이터와 UI 상태의 책임 구조

Next.js Route Handler / server data layer
│
├─ Server Component
│  ├─ 필요한 경우 server cache
│  ├─ QueryClient.query로 초기 데이터 준비
│  └─ dehydrate
│
├─ HydrationBoundary
│
└─ Client TaskFlow
   ├─ useQuery
   ├─ useMutation
   ├─ queryKey
   ├─ invalidateQueries
   ├─ optimistic update
   └─ rollback


클라이언트 UI 상태
→ Zustand / React state

mutation 이후 최종 흐름

사용자 작업 수정
→ useMutation
→ Route Handler / 서버 저장
→ 서버 캐시가 있다면 서버 측 revalidation
→ 브라우저 Query cache invalidation
→ 최신 데이터 refetch
→ UI 동기화

최종 학습 체크리스트

• 서버 상태와 클라이언트 UI 상태를 구분할 수 있습니다.
• QueryClientProvider와 useQuery를 구성할 수 있습니다.
• queryFn과 queryKey를 설계할 수 있습니다.
• staleTime과 gcTime을 구분할 수 있습니다.
• useMutation과 invalidation을 연결할 수 있습니다.
• pagination과 infinite query를 구현할 수 있습니다.
• optimistic update와 rollback을 구현할 수 있습니다.
• 목록·상세 cache 동기화 전략을 선택할 수 있습니다.
• Server Component에서 Query cache를 준비할 수 있습니다.
• dehydrate와 HydrationBoundary를 연결할 수 있습니다.
• QueryClient 생명주기 오류를 진단할 수 있습니다.
• Next.js 서버 cache와 TanStack Query cache의 책임을 구분할 수 있습니다.

# 캐시 소유권 최종 점검

1. 서버 demo 메모리 저장소: Route Handler와 Server Component가 같은 listTasks 함수를 사용합니다. 영속 DB가 아닙니다.
2. /tasks는 force-dynamic이고 /api/tasks는 private, no-store입니다. 브라우저 HTTP 캐시를 Query 캐시로 오해하지 않습니다.
3. QueryClient: 서버는 요청마다 새로 생성, 브라우저는 재사용합니다. 서버 snapshot을 dehydrate한 뒤 HydrationBoundary로 전달합니다.
4. POST/PATCH 성공은 taskKeys.all 무효화. optimistic 실패는 저장한 목록·상세 snapshot으로 복원 후 서버 결과 재확인.
5. 이 예제는 인증 전 demo 트랙입니다. 실제 사용자 서비스로 확장할 때에는 사용자별 서버 권한·쿼리 경계·세션 변경 시 캐시 정리가 필요합니다.

query-step-14-hydration-fix

GET /api/tasks 원본
→ 서버 데이터 계층


브라우저 tasks cache
→ TanStack Query


작업 저장/수정/삭제
→ useMutation + Route Handler


브라우저 목록 갱신
→ invalidateQueries


서버에서 명시적으로 cache한 결과
→ Next.js revalidation


selectedTaskId / modal / UI 설정
→ Zustand 또는 React state

TanStack Query
→ tasks


Zustand
→ 같은 tasks 복사


Server cache
→ 같은 사용자별 tasks를 별도 장기 보관


컴포넌트 state
→ 또 tasks 복사

npm run build

query-step-15-cache-boundary

다음 학습

TanStack Query 이후에는 프로젝트 요구에 따라 다음 방향으로 확장할 수 있습니다.

클라이언트 전역 UI 상태 심화
→ Zustand


Next.js Cache Components·Server Actions 심화
→ Next.js 고급


실제 백엔드 연동
→ Firebase / Supabase / 별도 API


복잡한 mutation 흐름
→ offline mutation·mutation queue·실시간 동기화

공식 문서

• TanStack Query Advanced SSR: https://tanstack.com/query/latest/docs/framework/react/guides/advanced-ssr
• Next.js use cache: https://nextjs.org/docs/app/api-reference/directives/use-cache
• Next.js revalidatePath: https://nextjs.org/docs/app/api-reference/functions/revalidatePath

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

TanStack Query · 15 / 15 · 최종 설계 · Next.js와 Query 캐시 경계

Next.js App Router와 TanStack Query를 함께 사용하면 “둘 다 캐시를 제공하는데 무엇을 어디에 맡겨야 하는가?”라는 문제가 생깁니다.

핵심은 두 캐시가 같은 계층이 아니라는 점입니다.

TanStack Query는 브라우저 QueryClient가 queryKey 기준으로 서버 상태를 관리하고, Next.js 캐시는 서버 렌더링·데이터 계산 결과를 재사용하는 프레임워크 계층입니다.

현재 Next.js 16에서는 Cache Components가 도입되었고 cacheComponents를 활성화하면 use cache, cacheLife, cacheTag 같은 명시적 서버 캐싱 모델을 사용할 수 있습니다. Cache Components를 사용하지 않는 기존 모델에서도 fetch는 기본적으로 캐시되지 않으며 필요할 때 force-cache나 revalidation을 명시합니다.

이번 글에서 배우는 내용

• TanStack Query cache의 소유 위치
• Next.js 서버 캐시의 역할
• Next.js 16 Cache Components
• use cache와 Query cache 차이
• invalidateQueries와 revalidatePath 차이
• mutation 후 어느 캐시를 갱신해야 하는가
• 서버 데이터와 UI 상태의 책임 경계

목차