[Trouble Shooting] React Query의 QueryClient를 공통모듈에서 싱글톤으로 관리하기

📍 React Query의 QueryClient를 공통모듈에서 싱글톤으로 관리하기

배경

해외 TNA NOL 내재화를 마치고 NOL 도메인내에서도 리뷰를 작성할 수 있도록 공통모듈에 리뷰패키지를 추가하는 작업 때 마주한 고민이다. 리뷰는 PDP(상품 상세 페이지)에서 리뷰 조회, 신고가 가능하고 (내가 작성한 리뷰의 경우) 수정/삭제가 가능하며 예약 목록/상세 페이지에서 작성 및 수정이 가능한 구조이다.

문제 상황

예약 상세 페이지에서 리뷰를 작성하거나 수정한 후 PDP로 돌아가면, 추가/수정된 내용이 반영되지 않고 이전 데이터가 그대로 노출되는 문제가 발생했습니다.

 

원인 분석:

• 각 버티컬(PDP, 예약 등)이 독립적인 QueryClient 인스턴스를 생성하고 있었습니다.
• 예약 페이지에서 queryClient.invalidateQueries()를 호출해도, PDP의 QueryClient는 별도 인스턴스이기 때문에 캐시 무효화가 전파되지 않았습니다.
• 결과적으로 각 페이지가 서로 다른 캐시를 참조하게 되어 데이터 정합성 문제가 발생했습니다.

대안 분석

1. 각 버티컬의 _app.tsx에서 공통 Provider 사용

장점:

• 명시적이고 제어 가능한 구조

단점:

• 모든 버티컬에서 동일한 보일러플레이트 코드 추가 필요
• 실수로 누락하면 데이터 동기화 실패

2. 싱글톤 패턴으로 전역 QueryClient 관리 ✅

장점:

• 버티컬에서 추가 설정 불필요
• 모든 페이지가 동일한 캐시 참조
• 한 곳에서 invalidate, refetchQueries 해도 전역 반영

단점:

• 전역 스코프 변수 사용에 대한 우려가 있을 수 있으나, 이는 React Query 공식 문서에서도 권장하는 패턴 (참고)

코드

 

// AS-IS
// 문제 상황: 각 버티컬이 독립적인 QueryClient 생성
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { useState, type ReactNode } from 'react'

export function QueryClientProviders({ children }: { children: ReactNode }) {
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: {
            staleTime: 60 * 1000,
            refetchOnWindowFocus: false,
            retryOnMount: false,
            retry: false,
          },
        },
      }),
  )

  return (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  )
}


// TO-BE
// nol-query-client.tsx

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { useState, type ReactNode } from 'react'

let globalQueryClient: QueryClient | null = null

export function NolQueryClientProviders({ children }: { children: ReactNode }) {
  const [queryClient] = useState(getGlobalQueryClient)

  return (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  )
}

function getGlobalQueryClient() {
  if (!globalQueryClient) {
    globalQueryClient = new QueryClient({
      defaultOptions: {
        queries: {
          staleTime: 60 * 1000,
          refetchOnWindowFocus: false,
          retryOnMount: false,
          retry: false,
        },
      },
    })
  }
  return globalQueryClient
}

결론

급한 일정 속에서도 "왜 이 문제가 발생했는가?"를 분석하고, 여러 대안을 비교한 과정이 저에게는 가치 있었습니다. 완벽한 해결책은 없지만, 현재 상황에 가장 적합한 선택을 할 수 있던 계기였습니다.