React Query와 SSR: 서버 사이드 데이터 관리와 Hydration 활용

Project

React Query와 SSR: 서버 사이드 데이터 관리와 Hydration 활용

🐶zio 2024. 12. 7. 17:33

현재 프로젝트는 서버 사이드 렌더링(SSR)과 클라이언트 사이드 렌더링(CSR)이 혼합된 애플리케이션이다.

정적인 페이지: 데이터 변화가 적어 정적 콘텐츠로 제공 (e.g. 메인 화면)
동적인 페이지: 데이터 변화가 많아 업데이트가 잦음 (e.g. 게시물 리스트)

이러한 상황에서, 나는 정적인 페이지는 Next.js의 캐시 기능, 동적인 페이지는 React Query를 사용하면 좋을 것이라 생각했었다.

하지만 관리의 복잡성을 줄이기 위해 한 가지 방식으로 통일하는 것이 좋다는 피드백을 받았다.

그래서 React Query를 SSR 환경에서도 활용하는 방법을 고민했다.

React Query

React Query의 useQuery는 클라이언트 측 데이터 패칭을 도와준다.

SSR에서는 서버에서 데이터를 받아 완성된 HTML을 보내주기 때문에 React Query의 캐시를 클라이언트에서 바로 사용할 수 없다.

이를 해결하기 위해 서버에서 데이터를 미리 패칭하고, 클라이언트에서 React Query 캐시를 복원하는 방식을 사용한다.

SSR에서 React Query

1. dehydrate

서버에서 데이터를 미리 패칭하고, 이를 직렬화하여 클라이언트로 전달하는 역할을 한다.

2. HydrationBoundary

클라이언트 측에서 서버로부터 전달받은 데이터를 React Query 캐시에 복원(hydration)하는 역할을 한다.

동작 과정

1. 서버에서 데이터 패칭

React Query의 `prefetchQuery`를 사용해 데이터를 서버에서 미리 가져온다.

2. 클라이언트로 데이터 전송

서버에서 직렬화한 데이터를 `dehydrate`를 통해 클라이언트로 전달한다.

3. 클라이언트에서 데이터 하이드레이션

클라이언트는 `HydrationBoundary`를 통해 전달받은 데이터를 React Query 캐시에 저장하고 재사용한다.

예제 코드

0. Provider 설정

// queryProvider.ts

'use client';

import {
  isServer,
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { PropsWithChildren } from 'react';

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        // 임시 설정
        staleTime: 60 * 1000,
        refetchInterval: 60 * 1000,
      },
    },
  });
}

let browserQueryClient: QueryClient | undefined;

function getQueryClient() {
  if (isServer) return makeQueryClient();
  if (!browserQueryClient) browserQueryClient = makeQueryClient();
  return browserQueryClient;
}

function QueryProviders({ children }: PropsWithChildren) {
  const queryClient = getQueryClient();
  return (
    <QueryClientProvider client={queryClient}>
      <ReactQueryDevtools initialIsOpen={false} client={queryClient} />
      {children}
    </QueryClientProvider>
  );
}

export default QueryProviders;

makeQueryClient

역할: 리액트 쿼리의 QueryClient 객체를 생성한다.

defaultOptions을 사용해 쿼리 기본 동작(캐싱, 갱신 등)을 정의한다.

getQueryClient

역할: 서버와 브라우저 환경에 맞게 QueryClient를 관리한다.

서버 환경(isServer가 true)일 때, 항상 새로운 QueryClient를 생성한다. (서버에서는 요청 간 상태를 공유하면 안 되기 때문)
브라우저 환경(isServer가 false)일 때, 브라우저에서는 browserQueryClient라는 전역 변수에 저장하여 재사용한다. 동일한 QueryClient를 재사용해 캐시와 상태를 공유할 수 있다.

QueryProvisers

역할: getQueryClient로 설정한 QueryClient객체를 Provider를 통해 전역적으로 쿼리 상태를 공유한다.

// layout.tsx

import QueryProviders from '@/utils/queryProvider';

const RootLayout = async ({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) => {
  return (
    <html lang="ko">
      <body>
        <QueryProviders>
          {children}
        </QueryProviders>
      </body>
    </html>
  );
};

export default RootLayout;

1. 데이터 패칭 함수

jsonplaceholder를 이용한 더미 데이터 활용

export const fetchPosts = async (pageNum = 1) => {
  const response = await fetch(
    `https://jsonplaceholder.typicode.com/posts?_limit=10&_page=${pageNum}`,
  );
  return response.json();
};

2. SSR에서의 데이터 패칭과 Hydration

// page.tsx

import {
  dehydrate,
  HydrationBoundary,
  QueryClient,
} from '@tanstack/react-query';
import Posts from './Post';

const page = async () => {
  const queryClient = new QueryClient();

  // 서버에서 데이터 패칭
  await queryClient.prefetchQuery({
    queryKey: ['posts'],
    queryFn: () => fetchPosts(),
  });

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <h1>서버 사이드 렌더링 테스트</h1>
      <div>----------------------</div>
      <Posts />
    </HydrationBoundary>
  );
};

export default page;

HydrationBoundary : 서버에서 미리 패칭한 데이터를 클라이언트에서 복원하여 React Query 캐시로 사용 가능하게 한다.

3. 클라이언트에서 데이터 활용

Posts 컴포넌트는 React Query의 useQuery를 사용하여 데이터를 클라이언트에서 불러온다. 이미 하이드레이션된 데이터를 재사용하거나, 데이터가 없을 경우 새로 패칭한다.

// Posts.tsx

'use client';

import { useQuery } from '@tanstack/react-query';
import { fetchPosts } from './page';

const Posts = () => {
  console.log('Posts 컴포넌트');
  const { data } = useQuery({
    queryKey: ['posts'],
    queryFn: () => fetchPosts(),
  });
  return (
    <div>
      {data?.map((post) => (
        <div key={post.id}>
          <h3>{post.title}</h3>
          <p>{post.body}</p>
        </div>
      ))}
    </div>
  );
};

export default Posts;

React Query와 SSR의 이점

서버에서 데이터를 미리 가져오기: 페이지 로딩 속도가 빨라지고 SEO 최적화가 가능하다.
클라이언트에서 데이터 복원: 이미 가져온 데이터를 재사용하여 불필요한 추가 네트워크 요청을 줄인다.
유연한 데이터 관리: 정적/동적 페이지를 모두 효과적으로 처리할 수 있다.

참고로 SSR로 동작하는지 테스트 해보고 싶다면 자바스크립트를 끄고 렌더링하면 된다.

Next.js의 내장 캐싱 기능과 fetch에서의 조건부 캐싱(Conditional Request)을 통해 데이터의 stale 상태를 효율적으로 관리할 수 있게 되면서, ‘React Query를 계속 사용해야 할까?’라는 의문이 들었다.

React Query가 제공하는 캐싱, 에러 핸들링, 무한 스크롤 등 다양한 기능이 매력적이었기 때문에 많이 사용되었다. 지금도 React로 프로젝트를 진행한다면 React Query를 사용할 것 같다. 하지만 Next.js와 브라우저 fetch API의 기능들이 점점 더 발전하면서, 동일한 기능을 더 간단하게 구현할 수 있는 옵션들이 늘어나고 있다.

React Query의 기능은 여전히 강력하고 유용하지만, 앞으로는 여러가지를 고려해야 할 것 같다.

참고 자료

https://soobing.github.io/react/server-rendering-and-react-query/

서버에서 React Query prefetching 한 데이터 사용하기

Next.js나 Remix 같은 프레임워크 내에서 React-Query를 사용한다면, 서버 렌더링 될 때 요청 후 응답받은 데이터를 SPA 방식으로 전환되고 나서도 유지할 수 있을까요? 어떻게 가능할까요? React Query의 hy

soobing.github.io

https://sonblog.vercel.app/blogs/blog/nextjs/react-query-ssr

React Query SSR

react query에서 ssr을 적용하는 방법에 대해 정리합니다.

sonblog.vercel.app

https://tanstack.com/query/v5/docs/framework/react/guides/advanced-ssr

Advanced Server Rendering | TanStack Query React Docs

Welcome to the Advanced Server Rendering guide, where you will learn all about using React Query with streaming, Server Components and the Next.js app router. You might want to read the before this on...

tanstack.com