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

2026년 3월 4일 수정됨

📋 개요

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 14 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이면 서버 캐시가 클라이언트로 넘어가자마자 상해버려서 바로 또 리패치 칩니다.
        staleTime: 60 * 1000, 
      },
      dehydrate: {
        // 보류 중인 프로미스는 절대 클라이언트로 Hydrate 쏘지 마라는 Next.js 권장 옵션
        shouldDehydrateQuery: (query) =>
          defaultShouldDehydrateQuery(query) ||
          query.state.status === 'pending',
      }
    },
  });
}
 
// 🎉 클라이언트 싱글톤 안전망 변수
let browserQueryClient: QueryClient | undefined = undefined;
 
export function getQueryClient() {
  if (typeof window === 'undefined') {
    // 1️⃣ 지금 내가 서버 주방이라면? 
    // 전역 변수 공유 절대 금지! 요청 한 번마다 무조건 뼈대 새로 생성!
    return makeQueryClient();
  } else {
    // 2️⃣ 내가 지금 유저의 브라우저(폰) 안이라면?
    // 리액트가 렌더링을 수백 번 다시 돌아도 단 '하나'의 전역 인스턴스만 보존!
    if (!browserQueryClient) browserQueryClient = makeQueryClient();
    return browserQueryClient;
  }
}

2. 레이아웃 파괴 금지: Provider 껍데기 분리 (Boundary)

위에서 안전한 안전모 호스를 만들었다면, 이제 이걸 유저에게 감싸줘야 합니다.
절대 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 훅을 빨아먹을 수 있는 완벽한 아키텍처입니다!

🐣 영철이의 퇴근 일기

와, 진짜 소름 돋았다... 방금 영호 리드 님이 브라우저 콘솔에서 내가 만든 "전역 QueryClient" 하나 때문에 옆자리 내 동기의 프로필 토큰 캐시가 내 브라우저 화면에 똑같이 렌더링되는 걸 재현해주셨는데 등골이 싹 서늘해졌다;;

💡 오늘의 교훈: "Next.js App Router 시대에는 내가 짠 코드가 서버 주방에서 돌아가는지, 유저의 폰에서 돌아가는지를 구분 못 하면 대형 보안 사고(Cross-Request Leak) 가 발생한다. QueryClient는 클라이언트일 땐 전역 재사용 단 1개, 서버일 땐 무조건 요청당 1개씩 찍어내자(Factory)!"

난 그냥 쉽게 가려고 const queryClient = new QueryClient() 한 줄 띡 친 것 뿐인데, 그게 수만 명의 접속자가 같이 퍼먹는 거대한 공용 냄비가 될 줄이야 ㅋㅋㅋ. 오늘 집에 가서 Next.js로 사이드 프로젝트 세팅할 때 무조건 저 getQueryClient 보일러플레이트 복붙해놔야지!

📝 배운 내용 점검하기 (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() 실행 함수를 상단 전역에 두면 서버에선 공유 스토리지 스파게티(Leak)가 나고, 컴포넌트 내부에 const queryClient = new QueryClient() 냅다 치면 프론트에서 조금의 렌더링 터질 때마다 캐시 인스턴스가 계속 초기화(파괴)되어 데이터가 날아갑니다. 하지만 저렇게 useState(() => new ...) 콜백형식으로 넘겨주면, 가장 완벽하게 모든 유저(요청당 1개)마다 독립되면서도, 컴포넌트 생명주기 내내(브라우저가 켜져있는 한) 절대 재할당(파괴) 안 되는 1회성 초기화 가 보장됩니다!
오답 피드백: "영철 님, B번처럼 리렌더링마다 캐시통(QueryClient) 이 찢어발겨지면 화면 깜빡임이 어마어마할 겁니다. 캐시는 살려두는 게 목적이에요!"
📌 핵심 기억법: 인스턴스 생명 연장술의 꽃, useState(() => init) 지연 초기화(Lazy Init)!