🧙‍♂️ Next.js와 React Query의 SSR 마법: 서버와 클라이언트 사이의 완벽한 조화

들어가며

프론트엔드 개발자라면 한 번쯤은 이런 고민을 해보셨을 겁니다: "데이터를 어떻게 효율적으로 관리하지?" React Query(Tanstack Query)는 이런 고민에 대한 강력한 해답을 제시했습니다. 하지만 Next.js의 SSR 환경에서는 약간의 마법 주문이 더 필요하죠!

이 글에서는 Next.js와 React Query를 함께 사용할 때의 SSR 최적화 전략에 대해 알아보겠습니다. 3가지 다른 방법을 비교하여 여러분의 프로젝트에 가장 적합한 방법을 찾는 데 도움이 되길 바랍니다.

SSR이 필요한 이유: 빠른 페이지, 행복한 사용자

먼저, 왜 SSR이 필요한지 살펴봅시다:

1. 초기 로딩 속도 개선: 서버에서 미리 렌더링된 HTML을 받아 사용자에게 즉시 컨텐츠를 보여줄 수 있습니다.

2. SEO 최적화: 검색 엔진 봇이 JavaScript를 실행하지 않고도 컨텐츠를 읽을 수 있어 검색 노출에 유리합니다.

3. 성능 향상: 클라이언트의 리소스 사용을 줄여 더 나은 성능을 제공합니다.

4. 사용자 경험 개선: 초기 로딩 시 빈 화면이나 로딩 스피너 대신 컨텐츠를 바로 볼 수 있어 사용자 경험이 향상됩니다.

Tanstack Query를 SSR과 함께 사용하면 이러한 장점을 모두 활용할 수 있습니다. 그럼 어떻게 설정해야 할까요?

SSR을 위한 React Query Provider 설정

Next.js에서는 클라이언트 코드를 루트 레벨에서 바로 사용할 수 없기 때문에, 별도의 Provider를 만들어 애플리케이션에 제공해야 합니다.

'use client';

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

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        // SSR의 경우, 기본 staleTime을 0 이상으로 설정하여 
        // 클라이언트에서 즉시 다시 가져오는 것을 방지합니다.
        staleTime: 60 * 1000,
      },
    },
  });
}

let browserQueryClient: QueryClient | undefined;

function getQueryClient() {
  if (isServer) {
    // 서버에서는 항상 새로운 queryClient를 만듭니다.
    return makeQueryClient();
  }
  // 브라우저에서는 queryClient가 없으면 새로운 queryClient를 만듭니다.
  if (!browserQueryClient) browserQueryClient = makeQueryClient();
  return browserQueryClient;
}

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

  return (
    <QueryClientProvider client={queryClient}>
      <ReactQueryStreamedHydration>
        <ReactQueryDevtools initialIsOpen={false} client={queryClient} />
        {children}
      </ReactQueryStreamedHydration>
    </QueryClientProvider>
  );
}

이제 Next.js의 루트 레이아웃에서 이 Provider를 사용할 수 있습니다.

Tanstack Query의 SSR 최적화 3가지 방법

React Query와 Next.js를 함께 사용할 때 3가지 주요 방법이 있습니다. 각각의 장단점을 살펴보겠습니다.

1. initialData 사용하기: 간단하지만 강력한 방법

initialData 옵션은 가장 간단한 접근 방식으로, 서버에서 가져온 데이터를 직접 클라이언트에 전달합니다.

동작 원리:

1. 서버에서 데이터를 가져옵니다.
2. 가져온 데이터를 props로 컴포넌트에 전달합니다.
3. 클라이언트에서 useQuery 훅의 initialData 옵션에 이 데이터를 전달합니다.

'use client';
import { useQuery } from '@tanstack/react-query';

const fetchTodos = async () => {
  const res = await fetch('https://api.example.com/todos');
  return res.json();
};

export async function getServerSideProps() {
  const todos = await fetchTodos();

  return {
    props: {
      todos,
    },
  };
}

function Home({ todos }) {
  const { data } = useQuery(['todos'], fetchTodos, {
    initialData: todos,
  });

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

export default Home;

2. PrefetchedQueryHydrationBoundary 사용하기: 여러 쿼리를 한번에

PrefetchedQueryHydrationBoundary는 더 복잡한 데이터 요구사항을 가진 페이지에 적합한 방법입니다. 특히 여러 쿼리를 한 번에 처리해야 할 때 유용합니다.

다음은 실제 프로젝트에서의 사용 예시입니다:

import fetcher from 'api/fetcher';
import { queryKey } from 'api/queryKey';
import PrefetchedQueryHydrationBoundary from 'api/PrefetchedQueryHydrationBoundary';
import UserManagementPage from './clientPage';

const UserManagementPageWithSSR = () => {
  return (
    <PrefetchedQueryHydrationBoundary
      queryList={[
        { queryKey: [queryKey.fetchUsers], queryFn: () => fetcher('users') },
      ]}
    >
      <UserManagementPage />
    </PrefetchedQueryHydrationBoundary>
  );
};

export default UserManagementPageWithSSR;

PrefetchedQueryHydrationBoundary 컴포넌트의 구현:

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

type PrefetchedQueryHydrationBoundaryProps<T> = {
  children: React.ReactNode;
  queryList: { queryKey: string[]; queryFn: QueryFunction<T> }[];
};

export default async function PrefetchedQueryHydrationBoundary<T>({
  children,
  queryList,
}: PrefetchedQueryHydrationBoundaryProps<T>) {
  const queryClient = new QueryClient();

  // 모든 쿼리를 병렬로 prefetch함
  await Promise.all(
    queryList.map(({ queryKey, queryFn }) =>
      queryClient.prefetchQuery({
        queryKey,
        queryFn,
      })
    )
  );

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

장점:

• 서버에서 데이터를 미리 가져와 초기 렌더링 시 데이터를 즉시 사용할 수 있습니다.
• 여러 쿼리를 한 번에 처리할 수 있어 복잡한 페이지에 적합합니다.

단점:

• 별도의 prefetch 함수를 구현해야 합니다.
• 클라이언트 페이지를 감싸는 SSR 페이지를 별도로 만들어야 합니다.

3. @tanstack/react-query-next-experimental 사용하기: 미래를 향한 도전

@tanstack/react-query-next-experimental 패키지는 Next.js와 Tanstack Query를 더 자연스럽게 통합합니다. 특히 useSuspenseQuery 훅을 사용하면 React의 Suspense와 함께 더 선언적인 데이터 로딩을 구현할 수 있습니다.

import { useSuspenseQuery } from '@tanstack/react-query';
import { queryKey } from 'api/queryKey';
import fetcher from '../../fetcher';
import { Robot } from '../types';

export const useFetchRobots = () => {
  return useSuspenseQuery<Robot[], Error>({
    queryKey: [queryKey.fetchRobots],
    queryFn: () => {
      return fetcher<Robot[], undefined>('robots');
    },
  });
};

장점:

• Suspense와 함께 사용하여 로딩 상태를 선언적으로 관리할 수 있습니다.
• 서버 컴포넌트와 클라이언트 컴포넌트 간의 데이터 흐름을 자연스럽게 처리할 수 있습니다.
• Next.js 13 이상의 App Router와 함께 사용하기 적합합니다.

단점:

• 아직 실험적인 패키지이므로 프로덕션 환경에서 사용 시 주의가 필요합니다.
• Suspense를 활용하기 위한 추가적인 설정이 필요할 수 있습니다.

어떤 방법을 선택해야 할까요?

각 방법은 상황에 따라 적합한 사용 사례가 있습니다:

1. initialData: 간단한 데이터 요구사항을 가진 페이지나 빠르게 구현해야 하는 경우에 적합합니다.

2. PrefetchedQueryHydrationBoundary: 복잡한 데이터 구조나 여러 쿼리를 처리해야 하는 페이지에 적합합니다.

3. useSuspenseQuery: 최신 React 패턴을 활용하고, 더 선언적인 데이터 로딩을 구현하고 싶을 때 적합합니다.

결론: 상황에 맞는 선택이 중요합니다

Next.js와 Tanstack Query를 함께 사용하는 방법은 다양하며, 각 방법은 고유한 장단점을 가지고 있습니다. 프로젝트의 요구사항과 팀의 선호도에 따라 적절한 방법을 선택하는 것이 중요합니다.

기본적으로 제공되는 fetch 함수만으로는 캐싱, 무한 스크롤, 낙관적 업데이트 등 다양한 기능을 구현하기 어렵습니다. Tanstack Query는 이러한 복잡한 상태 관리를 간단하게 해주므로, SSR 환경에서도 적절한 방법으로 활용하는 것이 좋습니다.

세 가지 방법 중 여러분의 프로젝트에 가장 적합한 방법을 선택하여 Next.js와 React Query의 강력한 조합을 경험해보세요!

레퍼런스

• Tanstack Query SSR 가이드 v4
• Tanstack Query SSR 가이드 최신 버전