본문 바로가기
Q&A해결2026년 4월 26일1분 읽기

TanStack Query v6 suspense + RSC 충돌

Q
Query러너
조회 847댓글 1

Next.js 16 App Router + TanStack Query v6를 사용 중입니다. Server Component에서 데이터를 prefetch하고, 클라이언트에서 useSuspenseQuery로 받으려고 하는데 hydration mismatch와 무한 fetch가 번갈아 발생합니다.

v6에서 권장 패턴이 어떻게 되는지, RSC와 함께 쓸 때 가이드라인이 궁금합니다.

댓글 1

김김영삼7개월 전

TanStack Query v6 + Next.js 16(RSC) 조합의 정확한 권장 패턴은 v6 릴리스 시점부터 다소 바뀌었고, 공식 문서에도 반영이 늦어 혼란이 큽니다.

핵심 원칙 (먼저 정리)

  1. Server Component에서 prefetch → state를 직렬화 → Client Component에 hydrate
  2. useSuspenseQuery는 클라이언트 트리에서만
  3. QueryClient는 요청별로 생성 (singleton 절대 금지)

1) QueryClient — 요청별 인스턴스

// app/providers.tsx
'use client'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { useState } from 'react'

export function Providers({ children }: { children: React.ReactNode }) {
const [client] = useState(() => new QueryClient({
defaultOptions: {
queries: {
staleTime: 60 * 1000,
gcTime: 5 * 60 * 1000,
},
},
}))
return <QueryClientProvider client={client}>{children}</QueryClientProvider>
}

핵심: useState로 lazy 초기화. 모듈 레벨 singleton은 SSR에서 다른 사용자 데이터가 섞입니다.

2) Server Component에서 prefetch + dehydrate

// app/posts/page.tsx (Server Component)
import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query'
import { Posts } from './Posts'

export default async function PostsPage() {
const queryClient = new QueryClient()

await queryClient.prefetchQuery({
queryKey: ['posts'],
queryFn: () => fetch('https://api/posts').then(r => r.json()),
})

return (
<HydrationBoundary state={dehydrate(queryClient)}>
<Posts />
</HydrationBoundary>
)
}

3) Client Component에서 useSuspenseQuery

// app/posts/Posts.tsx
'use client'
import { useSuspenseQuery } from '@tanstack/react-query'
import { Suspense } from 'react'

function PostsList() {
const { data } = useSuspenseQuery({
queryKey: ['posts'],
queryFn: () => fetch('/api/posts').then(r => r.json()),
})
return <ul>{data.map(p => ...)} </ul>
}

export function Posts() {
return (
<Suspense fallback={<Loading />}>
<PostsList />
</Suspense>
)
}

4) 흔한 실수 4가지

a) queryFn이 서버·클라이언트 모두에서 호출

// 잘못 — 서버에서 절대 URL, 클라이언트에서 상대 URL이 필요
queryFn: () => fetch('/api/posts') // 서버에선 실패

// 해결 — 환경 따라
const baseURL = typeof window === 'undefined'
? process.env.INTERNAL_API_URL
: ''
queryFn: () => fetch(`${baseURL}/api/posts`)

b) Hydration mismatch — 서버/클라이언트 다른 시간 표시

// 잘못
const formatted = new Date().toLocaleString() // 매번 다른 값

// 해결 — 시간은 클라이언트에서만
'use client'
useEffect(() => { setNow(new Date()) }, [])

c) staleTime이 너무 짧음 → 즉시 refetch

// hydrate 직후 stale 판단되면 클라이언트에서 또 fetch
defaultOptions: {
queries: {
staleTime: 60 * 1000, // 충분히 큰 값
}
}

d) Suspense 경계 누락

// useSuspenseQuery는 반드시 Suspense 안에
<Suspense fallback={...}>
<ComponentUsingSuspenseQuery />
</Suspense>

5) v6 신기능 — streamedQuery

v6에서 SSE/streaming 응답을 query로 다루는 helper가 추가됐습니다.

import { streamedQuery } from '@tanstack/react-query'

const { data } = useQuery({
queryKey: ['ai-response', prompt],
queryFn: streamedQuery({
queryFn: async ({ signal }) => {
const res = await fetch('/api/llm', { signal, body: prompt })
return res.body // ReadableStream
}
}),
})

스트리밍 응답을 점진적으로 갱신하는 패턴이 1급 시민이 됐습니다.

6) 디버깅 도구

import { ReactQueryDevtools } from '@tanstack/react-query-devtools'

<QueryClientProvider client={client}>
{children}
{process.env.NODE_ENV === 'development' && <ReactQueryDevtools />}
</QueryClientProvider>

devtools에서 server/client 각각의 cache 상태를 비교하면 hydration mismatch를 1분 안에 찾습니다.

실무 체크리스트

  1. QueryClient는 useState로 요청별 생성
  2. Server Component에서 prefetch + HydrationBoundary
  3. Client Component에서 useSuspenseQuery
  4. queryFn 내부 환경별 URL 처리
  5. staleTime 충분히 (1~5분)
  6. Suspense 경계 명확하게
  7. devtools 활용

큰 그림 — 정말 TanStack Query가 필요한가?

RSC가 충분히 강력해서 단순 데이터 fetch는 RSC만으로 끝납니다. TanStack Query는 다음 경우에만 도입 정당화:

  • infinite scroll·optimistic update·mutation 많음
  • 복잡한 캐시 무효화 정책
  • 실시간(WebSocket·SSE) 데이터와 query 통합

단순 CRUD라면 RSC + Server Actions로도 충분합니다. 라이브러리를 쓰지 않는 결정도 한 옵션입니다.

Ctrl+Enter로 등록