Next.js 12 에서 React Query v4 + SSR 활용하기

 

본 문서에서는, Next.js 12에서 React-query 를 적용하는 방법을 알아볼 것이다. 

클라이언트 사이드에서 사용하는지, 서버 사이드에서 사용하는지에 따라서 구체적인 사용 방법과 동작 방식에 차이가 있다.

 

https://tanstack.com/query/v4/docs/framework/react/guides/ssr

 

🔹 1. 클라이언트에서만 React Query 사용 (기본)

// pages/users.tsx
import { useQuery } from '@tanstack/react-query';

export default function Users() {
  const { data, isLoading } = useQuery(['users'], fetchUsers);
  ...
}

 

• useQuery는 클라이언트에서 작동 → CSR 기반
• 서버는 단순히 HTML 셸을 렌더하고, 데이터는 클라이언트에서 fetch

➡️ 장점: UX 빠름, 캐시 재사용 가능
➡️ 단점: SEO 및 초기 LCP 속도 한계

 

🔹 2. SSR/SSG + React Query 사용 (Hydration 방식)

SSR에서 데이터를 미리 fetch → React Query로 Hydrate하는 방식

// pages/users.tsx
import { QueryClient, dehydrate } from '@tanstack/react-query';

export async function getServerSideProps() {
  const queryClient = new QueryClient();

  await queryClient.prefetchQuery(['users'], fetchUsers);

  return {
    props: {
      dehydratedState: dehydrate(queryClient),
    },
  };
}

 

<Hydrate state={pageProps.dehydratedState}>
  <QueryComponent />
</Hydrate>

 

 

➡️ 서버에서 데이터를 미리 불러오고 HTML에 포함 → SEO, LCP, FCP 성능 향상
➡️ 클라이언트에서는 이미 캐시된 데이터로 즉시 렌더링

 

 

단순 SSR만 사용하는 것과 SSR/SSG + React Query 를 함께 사용하는 것 사이에 무슨 차이가 있는지 궁금할 수 있다. 

 

1. 단순 SSR만 사용하는 경우

• 서버에서 getServerSideProps 같은 함수로 데이터를 fetch하고, HTML에 포함시켜서 클라이언트로 보냄
• 클라이언트는 이미 데이터가 포함된 HTML을 받아 렌더링하므로, 초기 로딩이 빠름
• 하지만 이후, 클라이언트 쪽의 상태 관리나 캐싱은 따로 구현해줘야 함
• 페이지 이동 시에도 다시 SSR이 일어나기 때문에 네트워크 비용이 반복됨

🔸 단점: 데이터 재활용 불가, 클라이언트 상태 관리 부족, 추가 API 호출 발생 가능성

 

2. SSR/SSG + React Query 사용

• 서버에서 React Query를 통해 데이터를 fetch하고, dehydrate()로 초기 캐시 상태를 HTML에 주입
• 클라이언트는 hydrate()로 캐시된 데이터로 바로 렌더링, 추가 API 요청 없이도 바로 인터랙션 가능
• 페이지 이동 시에도 React Query 캐시를 재활용, 불필요한 refetch 방지
• staleTime, cacheTime 등을 설정해 데이터 freshness도 조절 가능

✅ 장점: CSR에서도 부드럽게 동작, 데이터 중복 요청 없음, 초기 로딩 속도 + UX + 캐싱 전략 최적화

 

 

SSR/SSG + React Query 구현 방식

 

https://tanstack.com/query/latest/docs/framework/react/guides/ssr#server-rendering--react-query

Server Rendering & Hydration | TanStack Query React Docs

 

 

이를 구현하는 방식에는 크게 두가지가 있다.

 

1️⃣ initialData 사용

서버에서 데이터를 fetch 한 다음 해당 props 를 useQuery() 함수의 initialData 옵션으로 원시 데이터를 전달하는 것

export async function getServerSideProps() {
  const posts = await getPosts()
  return { props: { posts } }
}

function Posts(props) {
  const { data } = useQuery({
    queryKey: ['posts'],
    queryFn: getPosts,
    initialData: props.posts,
  })

  // ...
}

 

setup이 간단하지만 몇가지 tradeoff 가 있다.

 

1. 하위 트리에서 useQuery 호출 시, initialData도 함께 전달해야 함

• 컴포넌트 트리 깊숙한 곳에서 useQuery를 사용할 경우, 해당 위치까지 initialData를 계속 props로 내려줘야 해서 번거롭고 복잡함.

2. 여러 곳에서 동일 쿼리를 쓰는 경우, 한 곳에만 initialData 전달하면 위험

• 하나의 컴포넌트만 initialData를 설정하고 다른 곳은 설정하지 않으면, 해당 컴포넌트가 사라질 때 나머지 컴포넌트들이 데이터를 못 받게 될 수 있음.
• 즉, 컴포넌트 재배치/리팩터링 시 취약해짐.

3. SSR에서 initialData는 정확한 fetch 시점을 모름

• initialData는 언제 데이터를 가져왔는지를 기록하지 않음 (dataUpdatedAt 없음).
• 그래서 페이지가 오래 열려 있어도 "언제 데이터가 생성됐는지" 모르기 때문에, 리패칭 판단이 어렵고 불안정함.

4. 캐시에 이미 데이터가 있다면, initialData는 덮어쓰기 안 됨

• 만약 캐시에 이전 데이터가 있고, 새로운 initialData가 실제로 더 최신이더라도 기존 데이터를 유지함.
• 특히 getServerSideProps 같은 경우, 페이지를 왔다갔다 할 때 매번 새로운 데이터를 받아오지만, 초기 데이터로만 캐시가 유지되므로 갱신되지 않음.

=> 즉, 정확하고 일관된 데이터 초기화에 지장을 받음

2️⃣ Hydration 사용

서버에서 query를 prefetch하고, 캐시를 dehydrate하고, client에서 rehydrate 한다. 클라이언트와 서버 모두에서 동일한 QueryClient 상태로 시작하여, SSR로 생성된 HTML과 클라이언트의 초기 마크업을 일치시키고, stale 캐시 문제를 방지할 수 있다.

 

 

🔄 단계별 설명

1. Preloading 단계 (서버 측)

• QueryClient를 생성:

const queryClient = new QueryClient();

• 필요한 쿼리를 미리 prefetch:

await Promise.all([
  queryClient.prefetchQuery(['todos'], fetchTodos),
  queryClient.prefetchQuery(['user', userId], fetchUser),
]);

• dehydrate(queryClient)로 직렬화하여 클라이언트에 전달:
  (예: getServerSideProps, loader, getStaticProps 등)

return {
  props: {
    dehydratedState: dehydrate(queryClient),
  },
};

 

🔧 dehydrate()란?

dehydrate(queryClient)는 React Query의 캐시 상태(queryClient.getQueryCache())를 직렬화 가능한 객체로 변환하는 함수입니다.

• "dehydrate" = 말 그대로 "수분을 제거하다" → 필요한 정보만 추려낸 요약 데이터
• React Query의 복잡한 내부 상태를 JSON처럼 클라이언트에 전달할 수 있는 단순한 형태로 만드는 것

 

2. 렌더링 단계 (서버 + 클라이언트)

• HydrationBoundary로 래핑하여 상태를 복원:

<HydrationBoundary state={dehydratedState}> <App /> </HydrationBoundary>

• dehydratedState는 서버와 클라이언트 각각의 QueryClient에 초기값을 공급.

🔁 왜 이걸 해야 하나요?

React Query는 기본적으로 클라이언트에서 데이터를 fetch합니다.
하지만 SSR에서는 서버에서 데이터를 미리 받아오고 그 결과를 클라이언트로 넘겨줄 수 있어야 하죠.

그래서:

1. 서버에서 데이터를 미리 fetch → queryClient에 저장됨
2. 그 queryClient를 dehydrate() 해서 JSON으로 만들고
3. 그걸 클라이언트에 props로 전달
4. 클라이언트는 <HydrationBoundary state={dehydratedState}>로 이 데이터를 다시 복원(hydrate)

이렇게 하면 초기 화면 렌더링 시점에서 클라이언트와 서버가 동일한 데이터를 기반으로 동작하게 됩니다.

🌟 이 방식의 장점

데이터 일관성	서버와 클라이언트가 동일한 캐시 상태에서 시작하여, hydration mismatch 방지
Refetch 타이밍 명확	dataUpdatedAt이 기록되므로, 오래된 데이터만 refetch됨
불필요한 API 호출 줄임	초기 캐시가 있어서 클라이언트에서 바로 refetch 안 해도 됨
유연성	일부는 prefetch하고, 나머지는 클라이언트에서만 fetch 가능 → 퍼포먼스 최적화 가능

 

⚠️ 주의할 점

• initialData와 달리 dehydratedState는 QueryClient 내부의 모든 쿼리 상태를 직렬화함.
• getServerSideProps / getStaticProps 외에도, Remix, RSC 등 각 프레임워크마다 적용 방식이 약간씩 다름.
• queryClient는 서버 prefetch용 / 서버 렌더링용 / 클라이언트용 총 3개가 사용됨:
  1. 서버 prefetch 용도 (loader 내부)
  2. SSR HTML 생성용
  3. 클라이언트 hydration 용도

 

🧠 기억할 점

initialData는 임시 응급처치,
dehydratedState + HydrationBoundary는 정확하고 확장 가능한 공식 해결책입니다.