🚀 09. Next.js App Router 환경에서의 TanStack Query 셋업

2026년 4월 30일 수정됨

📋 개요

React Query를 최신 Next.js App Router(RSC) 환경에 탑재할 때 필수적인 QueryClientProvider 싱글톤 세팅 전략과 메모리 릭 방지법을 다룹니다.

📋 목차

☕️ 영철이의 고민: "Next.js에서 Query 어떻게 켜나요?"
🤔 왜 알아야 하는가: 두 세계의 충돌
1. 전역 누수 방지: Request-Scoped QueryClient
2. 레이아웃 안정성 유지: Provider 껍데기 분리 (Boundary)
📝 배운 내용 점검하기 (Quiz)

"영철 님, Layout.tsx 파일 최상단에 use client를 붙이면 브라우저 번들과 메모리 사용량이 어떻게 달라지는지 먼저 확인해봅시다."

☕️ 영철이의 고민: "Next.js에서 Query 어떻게 켜나요?"

(월요일 아침, 브라우저가 버버벅거리는 현상을 겪는 영철)

🐣 영철: 리드 님! 저 혼자 주말에 Next.js App Router로 프로젝트 뼈대 다 만들어 놨거든요? 근데 React Query를 app/layout.tsx에 Provider로 감싸려니까 에러가 뜨더라고요. Provider는 리액트 훅을 쓰니까 당연히 클라이언트 컴포넌트잖아요? 그래서 layout.tsx 꼭대기에 'use client' 지시어를 붙이고 시작했죠!

🦁 영호: 영철 님, 그건 App Router의 서버 컴포넌트(RSC) 이점을 줄이는 위험한 선택입니다. 최상단 레이아웃 전체를 클라이언트로 밀어버리셨군요.
더 심각한 건, const queryClient = new QueryClient() 를 그냥 전역 변수로 선언하셨네요? 서버에서 이 방식은 다른 유저 A의 캐시가 유저 B의 요청에 섞일 수 있는 전역 메모리 오염(Cross-Request State Leak) 위험이 있습니다. 먼저 구조부터 분리해야 합니다.

🤔 왜 알아야 하는가: 두 세계의 충돌

SPA 시절 React 개발자들은 index.tsx 최상단 파일 밖에 const queryClient = new QueryClient() 하나를 선언해놓고 돌려썼습니다. 브라우저는 보통 한 사용자의 세션 안에서만 동작하니까요.

하지만 Next.js 13+ (App Router) 는 강력한 Node.js 서버 주방에서 컴포넌트가 구워집니다. 서버 공간은 수만 명의 유저 접속 요청이 동시에 빗발칩니다. 이 상황에서 서버 메모리 상의 전역 변수(싱글톤)로 QueryClient 인스턴스를 하나 덩그러니 만들어두면?
A 사용자가 페칭해 온 [user, me] 신상 정보 캐시가 0.1초 뒤 접속한 B 사용자의 화면에 그대로 히트(Cache Hit) 되버리는 치명적 개인정보 유출 사고 가 발생합니다.

이 단원에서는 RSC 세계관에서 완벽하고 안전하게 React Query를 설치하는 '정석(Boilerplate)' 셋업법을 익힙니다.

1. 전역 누수 방지: Request-Scoped QueryClient

정답은 "클라이언트 환경(브라우저)일 때는 전역 싱글톤을 쓰되, 서버 환경일 때는 반드시 사용자의 요청(Request) 1번당 1개의 QueryClient를 독립적으로 찍어낸다(Factory)" 입니다.

이는 Next.js와 TanStack Query 공식 문서에서 쐐기를 박은 팩토리 패턴입니다.
먼저 훅 기반 생성기 파일을 분리해야 합니다.

// 📝 app/providers/get-query-client.ts
import { QueryClient, defaultShouldDehydrateQuery } from '@tanstack/react-query';
 
// 딱 이 옵션 덩어리 하나만 잘 만들어 둡니다.
function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        // SSR 환경에서는 보통 0 이상으로 둡니다.
        // 0이면 서버 캐시가 클라이언트로 넘어가자마자 stale 상태가 되어 바로 다시 요청할 수 있습니다.
        staleTime: 60 * 1000,
      },
      dehydrate: {
        // 보류 중인 프로미스까지 클라이언트로 Hydrate할 수 있게 하는 옵션
        shouldDehydrateQuery: (query) =>
          defaultShouldDehydrateQuery(query) ||
          query.state.status === 'pending',
      }
    },
  });
}
 
// 🎉 클라이언트 싱글톤 안전망 변수
let browserQueryClient: QueryClient | undefined = undefined;
 
export function getQueryClient() {
  if (typeof window === 'undefined') {
    // 서버 환경에서는 요청 한 번마다 QueryClient를 새로 만든다.
    return makeQueryClient();
  } else {
    // 브라우저 환경에서는 렌더링이 반복되어도 하나의 인스턴스를 유지한다.
    if (!browserQueryClient) browserQueryClient = makeQueryClient();
    return browserQueryClient;
  }
}

2. 레이아웃 안정성 유지: Provider 껍데기 분리 (Boundary)

위에서 안전한 QueryClient 생성기를 만들었다면, 이제 이걸 앱에 주입해야 합니다.
layout.tsx 꼭대기에 'use client'를 붙이면 루트 레이아웃의 서버 컴포넌트 이점을 잃기 쉽습니다.
대신, Provider 껍데기 전용 클라이언트 컴포넌트 를 얇게 하나 분리해서 클라이언트 경계를 최소화합니다.

// 📝 app/providers/react-query-provider.tsx
'use client' // ❤️ 이것은 Provider 전용 껍질이다!
 
import { QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { getQueryClient } from './get-query-client';
 
export default function ReactQueryProvider({ children }: { children: React.ReactNode }) {
  // useState의 초기화값(Initializer) 패턴을 통해,
  // 렌더링이 일어날 때마다 클라이언트 객체를 다시 깎지 않도록 보장합니다!
  const queryClient = getQueryClient();
 
  return (
    <QueryClientProvider client={queryClient}>
      {children}
      {/* 덤으로 개발 도구도 여기서 심어준다 */}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

이 얇은 껍질을 완성했으니, 드디어 대망의 최상단 서버 주방인 layout.tsx 에 무사고 탑재할 수 있습니다.

// 📝 app/layout.tsx
// (여긴 순수 Server Component 영역입니다)
import ReactQueryProvider from './providers/react-query-provider';
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      <body>
        {/* 🚀 서버 컴포넌트의 거대한 트리를 Provider 바구니로 담아주기만 하면 끝! */}
        <ReactQueryProvider>
          {children}
        </ReactQueryProvider>
      </body>
    </html>
  );
}

이 구조는 layout.tsx 자체를 클라이언트 번들로 밀어 넣지 않으면서, 하위 클라이언트 컴포넌트가 필요한 곳에서 useQuery를 사용할 수 있게 해줍니다.

📝 배운 내용 점검하기 (Quiz)

Q. 다음과 같이 컴포넌트 내부에 useState를 이용해 QueryClient 클라이언트를 초기화(초깃값)하여 관리하는 방법이 있습니다. 이것이 훅스 원리상 올바른 방법이자 안전한 이유는 무엇입니까?

'use client'
import { QueryClientProvider, QueryClient } from '@tanstack/react-query'
import { useState } from 'react'
 
export default function Providers({ children }: { children: React.ReactNode }) {
  // 컴포넌트 내부에서 생성!
  const [queryClient] = useState(() => new QueryClient())
 
  return (
    <QueryClientProvider client={queryClient}>
      {children}
    </QueryClientProvider>
  )
}

A) useState 안에서 콜백 함수로 감싸 지연 초기화(Lazy Initialization)를 했으므로 컴포넌트가 아무리 리렌더링을 하더라도 절대 QueryClient를 재생성하지 않고 레퍼런스를 캐싱(유지)하기 때문입니다.
B) 브라우저 메모리에 무한정 캐시가 쌓이는 걸 막기 위해, 리렌더링마다 낡은 QueryClient가 덮어써져 초기화되도록 수명을 제한하기 때문입니다.
C) 저 코드는 틀린 코드입니다. useMemo를 반드시 사용해야 동일한 인스턴스가 유지됩니다.

✅ 정답: A

💡 상세 해설:

원리 설명: new QueryClient()를 서버 모듈 전역에 두면 요청 간 캐시 공유 위험이 생기고, 클라이언트 컴포넌트 본문에서 매 렌더마다 만들면 캐시 인스턴스가 계속 초기화됩니다. useState(() => new QueryClient())처럼 지연 초기화하면 브라우저 생명주기 동안 같은 인스턴스를 유지할 수 있습니다.
오답 피드백: "영철 님, B번처럼 리렌더링마다 QueryClient가 초기화되면 캐시를 유지할 수 없습니다. 캐시는 안정적인 인스턴스 위에서 의미가 생깁니다."
📌 핵심 기억법: 인스턴스 생명 연장술의 꽃, useState(() => init) 지연 초기화(Lazy Init)!

📝 마무리 퀴즈

Q1. Next.js App Router에서 QueryClient를 컴포넌트 렌더링마다 새로 만들면 어떤 문제가 생기나요?

✅ 정답: 렌더링 때마다 캐시 저장소가 바뀌어 기존 캐시가 유지되지 않고 불필요한 재요청과 상태 초기화가 발생할 수 있습니다.

💡 상세 해설:
QueryClient는 캐시 금고입니다. 클라이언트에서는 안정적인 인스턴스를 유지해야 같은 키의 데이터를 재사용할 수 있습니다. Provider 컴포넌트 안에서 useState(() => new QueryClient()) 같은 패턴을 쓰는 이유도 인스턴스 안정성 때문입니다.

Q2. App Router에서 TanStack Query Provider 파일에 'use client'가 필요한 이유는 무엇인가요?

✅ 정답: QueryClientProvider와 useQuery 기반 캐시 구독은 클라이언트 런타임에서 동작해야 하므로 클라이언트 컴포넌트 경계가 필요합니다.

💡 상세 해설:
서버 컴포넌트는 브라우저 상태를 구독하지 않습니다. Query Provider는 클라이언트 캐시와 훅을 위한 기반이므로 클라이언트 경계 안에 둬야 합니다. 다만 서버에서 프리페치한 결과는 이후 HydrationBoundary로 넘길 수 있습니다.

Q3. 영철이의 테스트 타임: 서버 컴포넌트에서 미리 가져온 데이터가 클라이언트 진입 직후 다시 fetch됩니다. 가장 먼저 점검할 설정은 무엇인가요?

✅ 정답: 프리페치된 데이터에 맞는 staleTime이 설정되어 있는지 확인합니다.

💡 상세 해설:
TanStack Query는 기본적으로 데이터가 즉시 stale입니다. SSR 직후 곧바로 재요청이 날아가는 것이 항상 버그는 아니지만, “방금 서버에서 받아온 데이터”라면 적절한 신선도 시간을 주어 중복 요청을 줄일 수 있습니다.

🐣 영철이의 퇴근 일기

오늘은 QueryClient 인스턴스의 위치가 보안과 성능을 동시에 좌우한다는 걸 배웠다. 브라우저에서는 하나의 안정적인 클라이언트를 재사용해야 캐시가 유지되지만, 서버에서는 요청별로 새 클라이언트를 만들어야 사용자 데이터가 섞이지 않는다.

💡 오늘의 교훈: "코드가 서버에서 도는지 브라우저에서 도는지 먼저 확인하자. QueryClient는 클라이언트에서는 안정적으로 재사용하고, 서버에서는 요청마다 새로 만든다."

내일은 Provider를 만들 때 layout.tsx에 바로 'use client'를 붙이지 말고, 얇은 provider 컴포넌트를 따로 만든 뒤 getQueryClient()의 서버/브라우저 분기를 먼저 확인해야겠다.