Suspense Query - 선언성을 댓가로 지불하는 Suspend 상태

useSuspenseQuery의 이점

data is guaranteed to be defined

// useQuery: 로딩과 에러를 직접 분기해야 합니다
const { data, isLoading, isError } = useQuery({
  queryKey: ['post', postId],
  queryFn: () => fetchPost(postId),
})

if (isLoading) return <Spinner />
if (isError) return <ErrorView />
return <Article post={data} /> // data의 타입은 Post | undefined

// useSuspenseQuery: 에러 및 로딩 분기가 사라지고 data가 보장됩니다
const { data } = useSuspenseQuery({
  queryKey: ['post', postId],
  queryFn: () => fetchPost(postId),
})

return <Article post={data} /> // data의 타입은 Post (undefined가 아님)

suspend는 결국 throw다

// suspend의 본질: render 도중 promise를 throw합니다
function Component() {
  if (!data) {
    throw fetchData() // 이 한 줄이 곧 suspend입니다
  }
  return <div>{data}</div>
}

받아 줄 경계가 없으면 화면이 사라진다

<App>                ◄── 여기까지 경계가 하나도 없으면 트리 전체가 무너집니다.
  └ <Layout>             에러가 트리를 끝까지 타고 올라갑니다.
      └ <PostList>   ──  여기서 throw 됩니다.

// 경계가 없으면 suspend도 에러도 받아 줄 곳이 없습니다
function Page() {
  return <PostList /> // 내부에서 useSuspenseQuery를 사용합니다
}

// Suspense와 ErrorBoundary로 감싸야 화면이 살아 있습니다
<ErrorBoundary fallback={<ErrorView />}>
  <Suspense fallback={<Skeleton />}>
    <PostList />
  </Suspense>
</ErrorBoundary>

경계를 어느 깊이에 둘 것인가

너무 높음:  화면 전체에 <Suspense> 하나   ◄── 작은 suspend에도 전체가 깜빡임
적당함:    의미 있는 영역마다 <Suspense>  ──  느린 영역만 fallback, 나머지는 즉시
너무 낮음:  요소 하나마다 <Suspense>      ◄── 팝콘처럼 따로따로 튀어 들어옴

// 화면을 의미 단위로 나눠, 영역마다 경계를 둡니다
<PageShell> {/* 셸과 레이아웃은 즉시 그려집니다 */}
  <ErrorBoundary fallback={<FeedError />}>
    <Suspense fallback={<FeedSkeleton />}>
      <Feed /> {/* 본문 피드는 한 덩어리로 등장합니다 */}
    </Suspense>
  </ErrorBoundary>

  <ErrorBoundary fallback={<SidebarError />}>
    <Suspense fallback={<SidebarSkeleton />}>
      <Sidebar /> {/* 사이드바는 피드와 독립적으로 채워집니다 */}
    </Suspense>
  </ErrorBoundary>
</PageShell>

경계만이 문제가 아닌 경우도 있다

// user가 suspend되는 동안 posts 요청은 시작도 못 합니다 (waterfall)
const { data: user } = useSuspenseQuery({
  queryKey: ['user'],
  queryFn: fetchUser,
})
const { data: posts } = useSuspenseQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
})

// 위 waterfall은 이 async/await와 같은 모양입니다
const user = await fetchUser()   // 끝나야
const posts = await fetchPosts() // 다음이 시작됩니다

// useSuspenseQueries로 묶으면 두 요청이 병렬로 나갑니다
const [{ data: user }, { data: posts }] = useSuspenseQueries({
  queries: [
    { queryKey: ['user'], queryFn: fetchUser },
    { queryKey: ['posts'], queryFn: fetchPosts },
  ],
})

Next.js에서 다시 보기

// 서버에서 미리 받아 두고 HydrationBoundary로 client에 넘깁니다
const queryClient = new QueryClient()
await queryClient.prefetchQuery({
  queryKey: ['post', id],
  queryFn: () => fetchPost(id),
})

return (
  <HydrationBoundary state={dehydrate(queryClient)}>
    <Post id={id} /> {/* 내부에서 useSuspenseQuery로 캐시된 데이터를 읽습니다 */}
  </HydrationBoundary>
)

잠깐, 컴파일타임에 막을 수는 없는가

// 경계까지 포함한 컴포넌트만 내보냅니다. 훅은 모듈 밖으로 노출하지 않습니다
export function Posts() {
  return (
    <ErrorBoundary fallback={<ErrorView />}>
      <Suspense fallback={<Skeleton />}>
        <PostsInner /> {/* 내부에서만 useSuspenseQuery를 부릅니다 */}
      </Suspense>
    </ErrorBoundary>
  )
}

그래서, 언제 의미있는가

마무리

참고 자료

• Suspense | TanStack Query React Docs

• useSuspenseQuery | TanStack Query React Docs

• Migrating to TanStack Query v5

• Announcing TanStack Query v5 | TanStack Blog

• Suspensive React Query