TanStack Query SSR prefetchQuery: Server Component에서 초기 데이터 준비하기

npm install @tanstack/react-query@5.104.0
node server-cache.mjs

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

async function prepareRequest(user) {
  const client = new QueryClient();
  await client.query({
    queryKey: ['items'],
    queryFn: async () => [{ id: 1, title: `${user}의 작업` }],
    staleTime: 60_000,
  });
  const value = client.getQueryData(['items']);
  client.clear();
  return value;
}
console.log(await prepareRequest('A'));
console.log(await prepareRequest('B'));

현재 API 변화

이전 v5 예제에서 자주 보이는 코드:

await queryClient.prefetchQuery({
  queryKey: ['tasks'],
  queryFn: getTasks,
});

현재 최신 문서 권장:

await queryClient.query({
  queryKey: ['tasks'],
  queryFn: getTasks,
});

prefetch 목적으로 결과값을 직접 사용하지 않아도 cache에는 결과가 저장됩니다.

오류를 페이지에 전파하지 않고 prefetch 실패만 무시하고 싶다면 프로젝트 정책에 따라 catch를 명시할 수 있습니다.

Server Component에서 QueryClient 생성

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


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


  // ...
}

서버에서 사용하는 QueryClient를 module 전역 singleton으로 만들어 모든 사용자 요청이 공유하게 하면 안 됩니다.

// 피하는 편이 좋은 서버 패턴
const queryClient =
  new QueryClient();

요청별 데이터가 같은 cache 객체에 섞일 수 있기 때문입니다.

서버 queryFn

Server Component에서는 자신의 Route Handler를 브라우저처럼 상대 URL fetch로 다시 호출하기보다, Route Handler가 사용하는 서버 데이터 계층을 직접 재사용하는 구조가 더 단순할 수 있습니다.

예를 들어 기존 Route Handler와 Server Component가 같은 서버 함수를 공유합니다.

// server/tasks.ts
import 'server-only';


export async function getTasksForServer():
  Promise<Task[]> {
  return taskRepository.list();
}

프로젝트의 실제 DB, Firebase, Supabase, ORM 구조에 맞게 서버 데이터 계층을 연결합니다.

queryClient.query 실행

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

이 시점에 서버 QueryClient cache에는 작업 목록이 들어 있습니다.

staleTime을 0보다 크게 두는 이유

서버에서 방금 가져온 데이터를 Hydration한 직후 클라이언트 useQuery가 곧바로 stale로 판단하면 브라우저에서 즉시 다시 요청할 수 있습니다.

SSR/Hydration 예제에서는 적절한 staleTime을 설정해 방금 준비한 데이터를 잠시 fresh로 보는 패턴이 일반적입니다.

new QueryClient({
  defaultOptions: {
    queries: {
      staleTime:
        60 * 1000,
    },
  },
});

정확한 시간은 데이터 특성에 따라 조정합니다.

서버와 클라이언트 queryKey 일치

서버:

queryKey:
  taskKeys.list('all')

클라이언트:

useQuery({
  queryKey:
    taskKeys.list('all'),
  queryFn: getTasks,
});

키가 다르면 서버에서 준비한 cache를 클라이언트 query가 재사용하지 못합니다.

아직 Hydration은 하지 않습니다

이번 회차의 목표는 서버 QueryClient에 데이터를 준비하는 것까지입니다.

다음 회차에서 다음 흐름을 완성합니다.

Server QueryClient
→ query()
→ cache 준비
→ dehydrate()
→ HydrationBoundary
→ Client QueryClient
→ useQuery

학습 완료 체크리스트

• 최신 문서의 API 권고와 제공된 예제의 설치 버전 범위를 구분할 수 있습니다.
• queryClient.query로 서버 cache를 준비할 수 있습니다.
• 서버 QueryClient를 요청 간 전역 공유하면 안 되는 이유를 설명할 수 있습니다.
• 서버와 클라이언트에서 같은 queryKey를 사용할 수 있습니다.
• 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 <><p>서버 prefetch 완료: {client.getQueryState(taskKeys.list('all'))?.status}</p><TaskDashboard /></>;
}

query-step-11-normalization

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


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>
      <p>
        서버 Query cache 준비 완료
      </p>
    </main>
  );
}

✓ 1~11. 조회·mutation·cache 설계
→ 12. Server Component prefetch
○ 13. dehydrate / HydrationBoundary
○ 14. Hydration 오류 해결
○ 15. Next.js cache 경계

query-step-12-ssr-prefetch

다음 학습

다음 글에서는 서버 QueryClient를 dehydrate하고 HydrationBoundary로 감싸 클라이언트 useQuery가 같은 cache 상태에서 시작하도록 연결합니다.

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

공식 문서

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

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

TanStack Query · 12 / 15 · 고급 학습 · Server Component prefetch

서버 데이터는 요청마다 만든 QueryClient에 미리 준비합니다. 이 준비만으로 브라우저 QueryClient에 전달되지는 않으며 dehydrate와 HydrationBoundary가 별도로 필요합니다. 아래 Node 예제로 A/B 요청의 캐시 분리를 확인하고, 하단에서는 전달 전 단계의 서버 상태를 관찰합니다.

2026-10-12에 확인한 최신 공식 문서는 prefetchQuery를 deprecated로 표시하고 query(options)를 권장합니다. 아래 Node 독립 예제는 원문에 고정된 @tanstack/react-query 5.104.0의 query를 사용하며, 누적 시작·완료 코드는 기존 prefetchQuery를 보존합니다. 제공된 package-lock과 코드의 설치 버전을 기준으로 실행하고 최신 문서의 API를 그대로 섞지 않습니다.

이번 글에서 배우는 내용

• Server Component에서 QueryClient 생성
• queryClient.query로 서버 prefetch
• prefetchQuery가 deprecated된 이유
• 서버 QueryClient를 요청 간 공유하면 안 되는 이유
• staleTime 설정
• dehydrate 준비
• 클라이언트 useQuery와 같은 queryKey 사용

목차