---
category: Frontend
tags: [auto-wikified, technical-documentation, frontend]
title: React Query (TanStack Query)
description: "React Query(TanStack Query)는 React 생태계에서 가장 성숙하고 잘 유지 관리되는 데이터 관리 라이브러리 중 하나입니다 [1]."
last_updated: 2026-05-04
---

# React Query (TanStack Query)

## 📌 Brief Summary
React Query(TanStack Query)는 React 생태계에서 가장 성숙하고 잘 유지 관리되는 데이터 관리 라이브러리 중 하나입니다 [1]. React Server Components(RSC)와 같은 최신 환경에서도 원활하게 작동하며, 데이터 로딩, 캐싱, 그리고 서버 데이터 동기화를 위임하여 클라이언트 로직을 크게 단순화하는 데 사용됩니다 [1, 2]. React 웹 애플리케이션뿐만 아니라 React Native를 활용한 모바일 개발 환경에서도 서버 상태 관리를 위한 실전 표준으로 자리 잡고 있습니다 [2].

## 📖 Core Content
*   **데이터 로딩 및 SSR 통합**
    React Query는 클라이언트 컴포넌트 내부에서 `useSuspenseQuery` 훅을 사용하여 데이터를 효율적으로 로드할 수 있습니다 [3]. `"use client"` 지시어 프래그마를 사용하더라도, 초기 페이지 로드 시에는 서버 사이드에서 데이터 페칭(Fetch)이 발생합니다 [3]. URL 변경에 따라 브라우저 측에서 새로운 쿼리가 실행될 때, 기존 UI가 로딩 상태(Suspense fallback)로 인해 사라지는 것을 방지하기 위해 `startTransition`으로 라우팅 로직을 감싸는 패턴이 활용됩니다 [3, 4].

*   **데이터 업데이트와 무효화 (Invalidation)**
    데이터를 업데이트(Mutation)한 후, 프론트엔드의 데이터를 최신 상태로 동기화하기 위해 `queryClient.invalidateQueries` API를 사용합니다 [5]. 쿼리 키(Query Key)의 첫 번째 부분을 전달하여 무효화하면, 해당 키로 시작하는 모든 캐시가 지워지고 화면에 활성화된 쿼리들이 즉시 다시 실행되어 UI가 갱신됩니다 [5]. 

*   **프리패칭(Prefetching)을 통한 성능 최적화**
    Next.js의 앱 라우터 환경에서 URL 파라미터가 변경될 때 프레임워크가 페이지를 새로 렌더링하는 과정에서 지연이 발생할 수 있습니다 [6, 7]. 이를 해결하기 위해 `queryClient.prefetchQuery`를 호출하여 새로운 데이터 요청을 미리 실행시킬 수 있습니다 [7, 8]. 이렇게 하면 Next.js의 네비게이션이 완료된 후 React Query가 데이터 요청을 보낼 때, 이미 진행 중인 프로미스(Promise)를 가로채어 결과를 즉시 사용할 수 있으므로 네트워크 병목이 해소됩니다 [8].

*   **모바일 환경(React Native)에서의 서버 상태 관리 위임**
    React Native 생태계에서도 React Query는 서버 상태 관리에 특화된 도구로 폭넓게 채택되고 있습니다 [2, 9]. 서버 데이터 동기화와 캐싱 로직을 프레임워크에 위임함으로써 클라이언트 측의 로직을 단순화하는 아키텍처 패턴이 강하게 권장됩니다 [2]. 

## ⚖️ Trade-offs & Caveats
*   **왕복 통신(Roundtrip)의 증가**
    데이터를 업데이트하고 화면에 반영할 때, 브라우저에서 서버로 두 번의 왕복 통신(첫 번째는 데이터 업데이트 요청, 두 번째는 `invalidateQueries`에 의한 새로운 데이터 페칭)이 발생합니다 [10]. 하지만 Next.js의 Server Action이 `revalidateTag`를 통해 전체 컴포넌트 트리와 모든 데이터를 다시 로드하는 것에 비하면, React Query의 방식이 더 빠르고 효율적인 경우가 많습니다 [10, 11].
*   **번들 크기(Bundle Size) 증가**
    React Query를 사용하기 위해 컴포넌트에 `"use client"`를 선언하게 되면, 해당 컴포넌트는 서버뿐만 아니라 클라이언트 환경에서도 실행되어야 하므로 자바스크립트 번들 크기가 다소 증가하게 됩니다 [12]. 하지만 다수의 데이터 소스와 상호작용이 존재하는 애플리케이션에서는 이러한 약간의 번들 크기 증가를 감수하더라도 복잡성을 줄이는 편이 훨씬 유리합니다 [12, 13].
*   **SSR 시 쿠키(Cookie) 누락 문제**
    Next.js 서버에서 SSR을 수행하는 동안 백엔드 API로 보내는 fetch 요청에는 인증 정보 등의 쿠키가 자동으로 포함되지 않습니다 [14, 15]. 이를 해결하려면 최상위 서버 컴포넌트에서 쿠키를 읽어 클라이언트 프로바이더(Provider)로 전달해야 하는데, 이 경우 보안 쿠키가 클라이언트 번들에 노출될 위험이 존재합니다 [16, 17]. 따라서 서버에만 노출되도록 쿠키를 암호화하는 별도의 라이브러리 사용 등의 우회적인 보안 처리가 필요합니다 [15-17].

---
*Last updated: 2026-05-03*