React Suspense + React Query: 로딩/에러 경계 설계와 waterfall 방지 패턴

React Suspense + React Query: 로딩/에러 경계 설계와 waterfall 방지 패턴

Suspense는 로딩 UI를 선언적으로 만들 수 있지만, boundary를 잘못 두면 waterfall(연쇄 요청)과 에러 처리 난이도가 급격히 올라갑니다. 이 글은 React Query와 함께 Suspense를 쓸 때의 실무 패턴(로딩/에러 경계, prefetch, staleTime)을 정리합니다.

Suspense는 경계를 어디에 두느냐가 체감 성능과 실패 격리를 좌우합니다.

옵션/핵심 요소(3~6개)

항목	의미	언제 쓰는지(실무 상황)
Suspense boundary	로딩 대체 UI 범위	페이지 전체 vs 섹션 단위로 쪼개 체감 속도 개선
Error boundary	에러 대체 UI 범위	한 섹션 실패가 전체 화면을 죽이지 않게 분리
prefetch	사전 로딩	라우팅/hover 직전에 미리 받아 waterfall 감소
staleTime	캐시 신선도	탭 이동/뒤로가기에서 불필요 재요청 방지
query key	캐시 분리 기준	필터/페이지네이션이 섞일 때 키 설계가 핵심

예시 코드(개념)

function Page() {
  return (
    <ErrorBoundary fallback={<div>오류</div>}>
      <React.Suspense fallback={<div>로딩...</div>}>
        <ProfileSection />
      </React.Suspense>
    </ErrorBoundary>
  )
}

function ProfileSection() {
  const { data } = useSuspenseQuery({ queryKey: ['me'], queryFn: fetchMe, staleTime: 30_000 })
  return <div>{data.name}</div>

문제 상황(정확히 1개)

상황: 페이지 진입 시 요청이 순차적으로만 나가 로딩이 길고, 섹션이 하나씩 늦게 뜬다

원인: 하위 컴포넌트에서 데이터 요청이 연쇄적으로 시작되어 waterfall이 생겼고, boundary가 병렬 로딩에 불리하게 배치됐다

해결: 상위에서 필요한 데이터를 prefetch하거나 boundary를 섹션 단위로 재배치해 병렬 로딩이 가능하게 만든다

예방 팁: 페이지의 '핵심 데이터'를 먼저 정의하고 병렬 로딩이 가능한 컴포넌트 구조를 기본으로 잡는다

참고/출처

• React Docs: Suspense
• TanStack Query: Suspense