27 lines
4.6 KiB
Markdown
27 lines
4.6 KiB
Markdown
---
|
|
category: Frontend
|
|
tags: [auto-wikified, technical-documentation, frontend]
|
|
title: useSuspenseQuery
|
|
description: "`useSuspenseQuery`는 React 환경에서 손쉬운 데이터 관리를 위해 사용되는 React Query(TanStack Query) 라이브러리의 훅(Hook)입니다 [1, 2]."
|
|
last_updated: 2026-05-04
|
|
---
|
|
|
|
# useSuspenseQuery
|
|
|
|
## 📌 Brief Summary
|
|
`useSuspenseQuery`는 React 환경에서 손쉬운 데이터 관리를 위해 사용되는 React Query(TanStack Query) 라이브러리의 훅(Hook)입니다 [1, 2]. 클라이언트 컴포넌트 내부에서 데이터를 가져올 때 주로 사용되며, React의 Suspense 기능과 결합하여 데이터가 로드되는 동안 UI의 렌더링을 중단(Suspend)시킬 수 있습니다 [2, 3]. 이를 통해 개발자는 데이터 로딩 상태 관리에 대한 복잡성을 덜고, React 서버 컴포넌트(RSC) 환경에서도 매끄러운 클라이언트 상호작용을 구현할 수 있습니다 [4].
|
|
|
|
## 📖 Core Content
|
|
* **초기 서버 렌더링 및 클라이언트 데이터 페칭:** `useSuspenseQuery`는 `"use client"` 지시어가 선언된 클라이언트 컴포넌트에서 사용되지만, 페이지의 초기 로드 시에는 서버에서 데이터 페칭(SSR)을 수행합니다 [2]. 초기 로드 이후 URL이 변경되는 등 상태가 변하면 브라우저 측에서 `useSuspenseQuery` 훅을 통해 새로운 쿼리가 실행됩니다 [2].
|
|
* **Suspense 및 트랜지션(Transition) 연동:** 브라우저에서 `useSuspenseQuery`가 새 데이터를 요청할 때 기본적으로 현재 UI를 중단(Suspend)시키고 가장 가까운 Suspense 경계에 있는 대체(fallback) UI를 화면에 보여줍니다 [2, 3]. 기존 화면이 사라지는 문제를 방지하기 위해 데이터를 트리거하는 액션(예: `router.push`)을 `startTransition`으로 감싸면, 데이터를 불러오는 동안 기존 콘텐츠를 계속 화면에 유지할 수 있습니다 [2].
|
|
* **사전 패칭(Prefetching)과의 결합:** 데이터 페칭 지연을 해결하기 위해 `queryClient.prefetchQuery` API와 결합하여 사용할 수 있습니다 [5]. `prefetchQuery`는 `useSuspenseQuery`와 동일한 옵션을 받아서 백그라운드에서 미리 쿼리를 실행하며, 이후 `useSuspenseQuery`가 동일한 쿼리를 시도할 때 진행 중인 프로미스(Promise)에 연결되어 데이터를 신속하게 반환합니다 [5].
|
|
* **인증 및 쿠키 전달:** SSR 과정 중 클라이언트 컴포넌트 내부의 `useSuspenseQuery`는 요청 쿠키에 직접 접근할 수 없으므로 인증된 요청을 보낼 수 없는 구조적 한계가 있습니다 [6]. 이를 우회하기 위해 최상단 RSC(React Server Component)에서 쿠키를 읽어 React Context에 전달하고, 클라이언트 컴포넌트 내의 `useSuspenseQuery`가 서버로 데이터 페치 요청을 보낼 때 쿠키를 포함시켜야 합니다 [6, 7].
|
|
|
|
## ⚖️ Trade-offs & Caveats
|
|
* **사용자 경험(UX) 저하 위험:** URL의 쿼리 문자열 변경 시 올바른 트랜지션(예: `startTransition`) 처리 없이 `useSuspenseQuery`가 업데이트되면 진행 중이던 UI가 갑자기 중단되고 폴백(fallback) 화면으로 교체되는 매우 불편한 사용자 경험을 초래할 수 있습니다 [3].
|
|
* **데이터 업데이트 시 이중 네트워크 왕복:** 데이터를 업데이트하고 관련된 쿼리를 무효화(`invalidateQueries`)할 경우, 데이터를 업데이트하는 첫 번째 왕복과 `useSuspenseQuery`가 새로운 데이터를 받아오기 위해 요청하는 두 번째 왕복 등 총 두 번의 브라우저-서버 간 네트워크 왕복이 필요합니다 [8]. (다만, 서버 액션(Server Actions)을 사용하여 전체 컴포넌트 트리를 다시 렌더링하는 것보다 이 두 번의 왕복이 더 빠를 때도 많습니다 [8]).
|
|
* **번들 크기 증가:** `useSuspenseQuery`를 활용하기 위해서는 해당 컴포넌트를 클라이언트 컴포넌트로 선언해야 합니다 [9]. RSC 환경에서 서버에만 존재하던 컴포넌트가 서버와 클라이언트 양쪽에서 모두 실행되어야 하므로 클라이언트 측 자바스크립트 번들 크기가 약간 증가하는 부작용이 동반됩니다 [9, 10].
|
|
* **보안 및 쿠키 노출 위험:** 인증 문제를 해결하기 위해 SSR의 쿠키를 Context를 통해 클라이언트 번들로 전달하면 보안에 취약한 `httpOnly` 쿠키가 클라이언트에 노출될 수 있습니다 [6]. 이를 방지하려면 서버에서만 안전하게 해독되도록 데이터를 암호화하는 별도의 라이브러리 연동 등 추가적인 보안 설계가 강제됩니다 [6, 7].
|
|
|
|
---
|
|
*Last updated: 2026-05-03* |