TanStack Query HydrationBoundary 사용법: 서버 데이터와 클라이언트 캐시 연결

import {
  QueryClient,
  QueryClientProvider,
  useQuery,
  HydrationBoundary,
  dehydrate
} from '@tanstack/react-query';

const client = new QueryClient({
  defaultOptions: { queries: { retry: false, refetchOnWindowFocus: false } },
});

// 서버가 보낸 것과 같은 직렬화 가능한 캐시 상태를 별도로 만듭니다.
const prepared = new QueryClient();
prepared.setQueryData(['hydrated-title'], { title: '준비된 제목' });
const transferred = JSON.parse(JSON.stringify(dehydrate(prepared)));
prepared.clear();
let requests = 0;
function Reader() {
  const query = useQuery({
    queryKey: ['hydrated-title'],
    queryFn: async () => { requests += 1; return { title: '다시 조회한 제목' }; },
    staleTime: 60_000,
  });
  return <p>{query.data?.title ?? '초기 대기'} / 후속 요청 {requests}</p>;
}
function Demo() {
  return (
    <HydrationBoundary state={transferred}>
      <Reader />
    </HydrationBoundary>
  );
}

export default function App() {
  return (
    <QueryClientProvider client={client}>
      <Demo />
    </QueryClientProvider>
  );
}

npm run dev
npm run build

전체 흐름

Server Component
→ QueryClient 생성
→ queryClient.query()
→ 서버 cache 준비
→ dehydrate(queryClient)
→ HydrationBoundary
→ Client Component
→ useQuery
→ 브라우저 QueryClient cache

서버와 브라우저가 같은 QueryClient 인스턴스를 공유하는 것은 아닙니다.

dehydrated state를 전달해 같은 데이터에서 시작하도록 연결합니다.

dehydrate

import {
  dehydrate,
} from '@tanstack/react-query';


const state =
  dehydrate(queryClient);

dehydrate는 QueryClient의 cache 상태를 전달 가능한 형태로 만듭니다.

기본적인 SSR 예제에서는 성공한 query를 서버에서 준비한 뒤 dehydrate합니다.

HydrationBoundary

import {
  HydrationBoundary,
  dehydrate,
} from '@tanstack/react-query';


return (
  <HydrationBoundary
    state={dehydrate(queryClient)}
  >
    <TaskListClient />
  </HydrationBoundary>
);

HydrationBoundary 아래의 Client Component가 같은 queryKey를 사용하면 서버에서 준비한 데이터를 브라우저 cache에 이어 받을 수 있습니다.

클라이언트 useQuery

'use client';


import {
  useQuery,
} from '@tanstack/react-query';
import {
  getTasks,
} from '../lib/tasks-api';
import {
  taskKeys,
} from '../lib/task-keys';


export default function TaskListClient() {
  const query = useQuery({
    queryKey:
      taskKeys.list('all'),
    queryFn: ({ signal }) =>
      getTasks(signal),
    staleTime: 60_000,
  });


  if (query.isPending) {
    return <p>불러오는 중입니다.</p>;
  }


  return (
    <ul>
      {query.data.map((task) => (
        <li key={task.id}>
          {task.title}
        </li>
      ))}
    </ul>
  );
}

서버와 클라이언트 queryKey가 정확히 같아야 합니다.

QueryClientProvider도 필요합니다

HydrationBoundary는 브라우저 QueryClient에 상태를 hydrate합니다.

따라서 앱 상위에는 QueryClientProvider가 있어야 합니다.

QueryClientProvider
└─ Server route output
   └─ HydrationBoundary
      └─ TaskListClient

아래 독립 예제는 QueryClientProvider와 소비할 QueryClient까지 함께 제공합니다. Next.js 앱에 적용할 때에는 상위 Client Provider 안에 HydrationBoundary가 들어가는 같은 관계를 유지합니다.

서버 page 전체 예제

import {
  dehydrate,
  HydrationBoundary,
  QueryClient,
} from '@tanstack/react-query';
import {
  taskKeys,
} from '../lib/task-keys';
import {
  getTasksForServer,
} from '../server/tasks';
import TaskListClient
  from './TaskListClient';


export default async function TasksPage() {
  const queryClient =
    new QueryClient({
      defaultOptions: {
        queries: {
          staleTime: 60_000,
        },
      },
    });


  await queryClient.query({
    queryKey:
      taskKeys.list('all'),
    queryFn:
      getTasksForServer,
  });


  return (
    <main>
      <h1>TaskFlow</h1>


      <HydrationBoundary
        state={
          dehydrate(
            queryClient,
          )
        }
      >
        <TaskListClient />
      </HydrationBoundary>
    </main>
  );
}

왜 staleTime을 함께 확인하는가

서버에서 방금 받은 데이터라도 클라이언트 query의 staleTime이 0이면 hydrate 직후 stale로 판단해 백그라운드 요청이 발생할 수 있습니다.

이것은 hydration 실패가 아니라 재검증 정책일 수 있습니다.

staleTime: 60_000

SSR로 전달한 데이터를 일정 시간 fresh로 보고 싶다면 서버와 클라이언트 query 정책을 맞춥니다.

initialData와 Hydration 차이

간단한 화면에서는 Server Component 데이터 값을 props로 넘기고 useQuery initialData를 사용할 수도 있습니다.

Hydration 방식은 query cache 자체를 서버에서 준비하므로 여러 query를 일관된 queryKey 체계로 연결할 때 유리합니다.

직렬화 가능한 데이터

서버에서 브라우저로 전달할 query data는 전송 가능한 형태인지 확인합니다.

복잡한 class instance나 특수 타입을 그대로 전달하는 구조라면 serialize/deserialize 정책이 필요할 수 있습니다.

TaskFlow의 Task처럼 일반 객체·문자열·boolean 위주라면 단순합니다.

학습 완료 체크리스트

• dehydrate가 서버 Query cache를 전달 가능한 상태로 만든다는 것을 이해했습니다.
• HydrationBoundary로 Client Component를 감쌀 수 있습니다.
• 서버와 브라우저 QueryClient가 별도 인스턴스임을 이해했습니다.
• 서버/클라이언트 queryKey를 일치시킬 수 있습니다.
• hydrate 직후 refetch와 hydration 실패를 구분할 수 있습니다.

export const dynamic = 'force-dynamic';
import { QueryClient, dehydrate, HydrationBoundary } from '@tanstack/react-query';
import { listTasks } from '@/app/lib/store';
import { taskKeys } from '@/app/lib/task-keys';
import TaskDashboard from '@/app/tasks/TaskDashboard';
export default async function TasksPage() {
  const client = new QueryClient();
  await client.prefetchQuery({ queryKey: taskKeys.list('all'), queryFn: async () => listTasks('demo'), staleTime: 30_000 });
  return <HydrationBoundary state={dehydrate(client)}><TaskDashboard /></HydrationBoundary>;
}

query-step-12-ssr-prefetch

app/tasks/page.tsx
app/tasks/TaskListClient.tsx
app/providers.tsx

서버 QueryClient에 데이터는 있지만
Client useQuery는 별도 cache로 시작

Server query()
→ dehydrate
→ HydrationBoundary
→ Client useQuery
→ 동일 queryKey cache 재사용

npm run build

✓ 1~12. Query·mutation·서버 prefetch
→ 13. HydrationBoundary
○ 14. Hydration 오류 진단
○ 15. Next.js cache 경계

query-step-13-hydration

다음 학습

다음 글에서는 QueryClient 생성 위치, queryKey 불일치, Provider와 HydrationBoundary 위치 때문에 hydration이 깨지거나 중복 요청처럼 보이는 문제를 진단합니다.

다음 프로젝트 단계: TanStack Query Hydration 오류 해결: QueryClient 설정 기준

공식 문서

• Advanced Server Rendering: https://tanstack.com/query/latest/docs/framework/react/guides/advanced-ssr
• dehydrate: https://tanstack.com/query/latest/docs/framework/react/reference/functions/dehydrate

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

TanStack Query · 13 / 15 · 고급 학습 · HydrationBoundary

서버와 브라우저는 별도 QueryClient를 사용합니다. 준비한 상태를 dehydrate하고 HydrationBoundary로 전달한 뒤 같은 queryKey의 useQuery가 읽게 합니다. 아래 독립 모형에서 준비용 client를 비운 뒤에도 전달된 제목을 읽는지 확인합니다.

TanStack Query에서는 서버 QueryClient를 dehydrate한 뒤 HydrationBoundary에 전달해 클라이언트 useQuery가 같은 queryKey의 데이터를 즉시 사용할 수 있게 합니다.

이번 글에서 배우는 내용

• dehydrate
• HydrationBoundary
• 서버 QueryClient와 브라우저 QueryClient의 차이
• 동일 queryKey 재사용
• 초기 HTML과 client cache 연결
• staleTime과 즉시 refetch
• Next.js App Router 구조

목차