Next.js 16 App Router + TanStack Query v6를 사용 중입니다. Server Component에서 데이터를 prefetch하고, 클라이언트에서 useSuspenseQuery로 받으려고 하는데 hydration mismatch와 무한 fetch가 번갈아 발생합니다.
v6에서 권장 패턴이 어떻게 되는지, RSC와 함께 쓸 때 가이드라인이 궁금합니다.
Next.js 16 App Router + TanStack Query v6를 사용 중입니다. Server Component에서 데이터를 prefetch하고, 클라이언트에서 useSuspenseQuery로 받으려고 하는데 hydration mismatch와 무한 fetch가 번갈아 발생합니다.
v6에서 권장 패턴이 어떻게 되는지, RSC와 함께 쓸 때 가이드라인이 궁금합니다.
댓글 1
TanStack Query v6 + Next.js 16(RSC) 조합의 정확한 권장 패턴은 v6 릴리스 시점부터 다소 바뀌었고, 공식 문서에도 반영이 늦어 혼란이 큽니다.
핵심 원칙 (먼저 정리)
1) QueryClient — 요청별 인스턴스
핵심:
useState로 lazy 초기화. 모듈 레벨 singleton은 SSR에서 다른 사용자 데이터가 섞입니다.2) Server Component에서 prefetch + dehydrate
3) Client Component에서 useSuspenseQuery
4) 흔한 실수 4가지
a) queryFn이 서버·클라이언트 모두에서 호출
b) Hydration mismatch — 서버/클라이언트 다른 시간 표시
c) staleTime이 너무 짧음 → 즉시 refetch
d) Suspense 경계 누락
5) v6 신기능 — streamedQuery
v6에서 SSE/streaming 응답을 query로 다루는 helper가 추가됐습니다.
스트리밍 응답을 점진적으로 갱신하는 패턴이 1급 시민이 됐습니다.
6) 디버깅 도구
devtools에서 server/client 각각의 cache 상태를 비교하면 hydration mismatch를 1분 안에 찾습니다.
실무 체크리스트
큰 그림 — 정말 TanStack Query가 필요한가?
RSC가 충분히 강력해서 단순 데이터 fetch는 RSC만으로 끝납니다. TanStack Query는 다음 경우에만 도입 정당화:
단순 CRUD라면 RSC + Server Actions로도 충분합니다. 라이브러리를 쓰지 않는 결정도 한 옵션입니다.