TanStack Query Hydration 오류 해결: QueryClient 설정 기준

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

const wait = (ms = 400) => new Promise<void>((resolve) => setTimeout(resolve, ms));

let requests = 0;
function Reader() {
  const query = useQuery({
    queryKey: ['lifecycle'],
    queryFn: async () => { await wait(); return ++requests; },
    staleTime: Infinity,
  });
  return <p>요청 번호 {query.data ?? '대기'}</p>;
}
export default function App() {
  const [stable] = useState(() => new QueryClient());
  const [broken, setBroken] = useState(false);
  const [render, setRender] = useState(0);
  const current = broken ? new QueryClient() : stable;
  return (
    <main>
      <label><input type="checkbox" checked={broken} onChange={(event) => setBroken(event.target.checked)} />매번 새 client</label>
      <button onClick={() => setRender((value) => value + 1)}>부모 재렌더 {render}</button>
      <QueryClientProvider client={current}>
        <Reader key={render} />
      </QueryClientProvider>
    </main>
  );
}

npm run dev
npm run build

문제 1. 서버 QueryClient를 전역 공유

다음 코드를 서버 요청이 함께 사용하는 module 전역 cache처럼 두는 것은 피하는 편이 좋습니다.

const queryClient =
  new QueryClient();

SSR 데이터가 사용자별일 수 있다면 요청 간 cache가 섞이는 위험이 있습니다.

서버에서는 새 QueryClient를 만들도록 구성합니다.

문제 2. 브라우저 QueryClient가 계속 새로 생성

반대로 브라우저에서는 렌더마다 QueryClient가 바뀌면 기존 cache가 사라질 수 있습니다.

function Providers({
  children,
}: {
  children: React.ReactNode;
}) {
  const queryClient =
    new QueryClient();


  return (
    <QueryClientProvider
      client={queryClient}
    >
      {children}
    </QueryClientProvider>
  );
}

안정적으로 유지합니다.

const [queryClient] =
  useState(
    () => makeQueryClient(),
  );

서버/브라우저를 구분하는 getQueryClient 패턴

현재 TanStack Query의 Next.js App Router 고급 가이드에서는 서버에서는 새 client를 만들고 브라우저에서는 singleton을 재사용하는 패턴을 보여줍니다.

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


function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60_000,
      },
    },
  });
}


let browserQueryClient:
  QueryClient | undefined;


export function getQueryClient() {
  if (isServer) {
    return makeQueryClient();
  }


  if (!browserQueryClient) {
    browserQueryClient =
      makeQueryClient();
  }


  return browserQueryClient;
}

프로젝트 구조에 따라 Provider에서 useState 패턴을 유지해도 되지만, Server Component prefetch와 공유하는 helper가 필요하다면 위처럼 역할을 명확히 할 수 있습니다.

문제 3. queryKey가 다름

서버:

queryKey: ['tasks']

클라이언트:

queryKey: [
  'tasks',
  'list',
  { status: 'all' },
]

이 두 query는 별도 cache입니다.

서버와 클라이언트 모두 같은 factory를 사용합니다.

taskKeys.list('all')

문제 4. HydrationBoundary 바깥에서 useQuery

HydrationBoundary
└─ A


B
└─ useQuery

B는 해당 boundary에서 전달된 dehydrated state를 적용받는 트리 밖에 있을 수 있습니다.

서버에서 준비한 query를 사용하는 Client Component를 boundary 아래에 배치합니다.

문제 5. QueryClientProvider가 없음

HydrationBoundary는 hydrate할 브라우저 QueryClient가 필요합니다.

앱 상위에서 QueryClientProvider가 실제 Client tree를 감싸는지 확인합니다.

문제 6. 즉시 refetch를 hydration 실패로 오해

기본 staleTime은 0입니다.

서버 cache가 정상 hydrate되어 화면이 즉시 표시되더라도 클라이언트에서 stale query를 다시 검증할 수 있습니다.

staleTime: 60_000

SSR 직후 재요청을 줄이고 싶다면 데이터 특성에 맞는 staleTime을 설정합니다.

Network에 GET이 한 번 더 보인다는 사실만으로 hydration 실패라고 판단하지 않습니다.

문제 7. 서버와 클라이언트 data shape가 다름

서버 queryFn:

Task[]

클라이언트 queryFn:

{ items: Task[] }

같은 queryKey로 서로 다른 data shape를 사용하면 렌더링 코드가 깨질 수 있습니다.

queryKey가 같다면 cache data contract도 같게 유지합니다.

문제 8. prefetch 오류가 숨겨짐

서버 query가 실패했는데 catch로 무조건 무시하면 dehydrate할 성공 데이터가 없을 수 있습니다.

초기 SSR 데이터가 필수라면 오류를 route error boundary로 전달할지, fallback을 보여줄지 정책을 정합니다.

진단 순서

1. 서버 query가 성공했는가
2. dehydrate 결과에 query가 있는가
3. 서버/클라이언트 queryKey가 같은가
4. Client Component가 HydrationBoundary 안에 있는가
5. QueryClientProvider가 상위에 있는가
6. 브라우저 QueryClient가 안정적으로 유지되는가
7. 서버 QueryClient가 요청 간 공유되지 않는가
8. staleTime 때문에 단순 refetch되는 것은 아닌가
9. data shape가 같은가

학습 완료 체크리스트

• 서버와 브라우저 QueryClient의 생명주기를 구분할 수 있습니다.
• queryKey 불일치를 진단할 수 있습니다.
• Provider와 HydrationBoundary 위치를 점검할 수 있습니다.
• 즉시 refetch와 hydration 실패를 구분할 수 있습니다.
• data shape 계약을 확인할 수 있습니다.

import { QueryClient } from '@tanstack/react-query';
function makeQueryClient() {
  return new QueryClient({ defaultOptions: { queries: { staleTime: 30_000, retry: false, refetchOnWindowFocus: false } } });
}
let browserClient: QueryClient | undefined;
export function getQueryClient() {
  if (typeof window === 'undefined') return makeQueryClient();
  return browserClient ??= makeQueryClient();
}

'use client';
import type { ReactNode } from 'react';
import { QueryClientProvider } from '@tanstack/react-query';
import { getQueryClient } from './lib/query-client';
export default function Providers({ children }: { children: ReactNode }) {
  return <QueryClientProvider client={getQueryClient()}>{children}</QueryClientProvider>;
}

query-step-13-hydration

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


function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60_000,
      },
    },
  });
}


let browserQueryClient:
  QueryClient | undefined;


export function getQueryClient() {
  if (isServer) {
    return makeQueryClient();
  }


  if (!browserQueryClient) {
    browserQueryClient =
      makeQueryClient();
  }


  return browserQueryClient;
}

'use client';


import {
  QueryClientProvider,
} from '@tanstack/react-query';
import {
  getQueryClient,
} from './get-query-client';


export default function Providers({
  children,
}: {
  children: React.ReactNode;
}) {
  const queryClient =
    getQueryClient();


  return (
    <QueryClientProvider
      client={queryClient}
    >
      {children}
    </QueryClientProvider>
  );
}

const queryClient =
  getQueryClient();


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

npm run build

query-step-14-hydration-fix

다음 학습

마지막 글에서는 Next.js 16의 서버 캐시 모델과 TanStack Query의 Query cache를 같은 흐름에서 비교하고, 어떤 계층이 어떤 데이터를 소유해야 하는지 최종 기준을 정합니다.

다음 프로젝트 단계: Next.js 캐시와 TanStack Query 캐시 차이: 서버·클라이언트 경계 설계

공식 문서

• Advanced Server Rendering: https://tanstack.com/query/latest/docs/framework/react/guides/advanced-ssr
• SSR & Hydration: https://tanstack.com/query/latest/docs/framework/react/guides/ssr

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

TanStack Query · 14 / 15 · 오류 해결 · Hydration

TanStack Query SSR을 적용한 뒤 “서버에서 분명 데이터를 가져왔는데 클라이언트가 다시 처음부터 요청한다”, “HydrationBoundary를 넣었는데 cache를 못 찾는다” 같은 문제가 생길 수 있습니다.

대부분은 QueryClient 생명주기, queryKey, Provider 위치, staleTime을 순서대로 확인하면 원인을 찾을 수 있습니다.

이번 글에서 배우는 내용

• 서버 QueryClient를 요청 간 공유하면 안 되는 이유
• 브라우저 QueryClient는 안정적으로 유지해야 하는 이유
• queryKey 불일치
• QueryClientProvider 위치
• HydrationBoundary 범위
• staleTime 0으로 인한 즉시 refetch
• 최소 재현 진단 순서

목차