TanStack Query v5 prefetchQuery + Next.js App Router: Render-as-You-Fetch와 스트리밍 SSR로 초기 로딩 제거하기

서버 Server Component
  └─ prefetchQuery() ──┐
                       ▼
                  QueryClient 캐시 채워짐
                       │
                  dehydrate() 직렬화
                       │
           스트리밍 HTML 응답 (청크 전송)
                       │
            클라이언트 HydrationBoundary
                       │
                  캐시 복원 (재요청 없음)
                       │
              useQuery() 즉시 데이터 반환

// v5.40.0 이전 — 모든 prefetch가 끝날 때까지 스트리밍 대기
await queryClient.prefetchQuery({ queryKey: ['posts'], queryFn: fetchPosts })
await queryClient.prefetchQuery({ queryKey: ['user'], queryFn: fetchUser })
// 느린 쪽이 끝나야 HTML 전송 시작
 
// v5.40.0 이후 — void로 시작해두고 즉시 스트리밍
void queryClient.prefetchQuery({ queryKey: ['posts'], queryFn: fetchPosts })
void queryClient.prefetchQuery({ queryKey: ['user'], queryFn: fetchUser })
// HTML 전송 시작, 각 쿼리가 resolve될 때마다 청크로 스트리밍

// lib/api.ts — 서버·클라이언트 공용 fetch 래퍼
export interface DashboardStats {
  revenue: number
  orderCount: number
  activeUsers: number
}
 
export async function fetchDashboardStats(): Promise<DashboardStats> {
  const res = await fetch('/api/dashboard/stats', { cache: 'no-store' })
  if (!res.ok) throw new Error('Failed to fetch dashboard stats')
  return res.json()
}

// app/dashboard/page.tsx (Server Component)
import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query'
import DashboardStats from './DashboardStats'
import { fetchDashboardStats } from '@/lib/api'
 
export default async function DashboardPage() {
  // 요청마다 새 QueryClient 생성 — 싱글톤으로 쓰면 서버 간 데이터 누수 발생
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60 * 1000, // 1분 — 없으면 클라이언트 마운트 즉시 리페치 발생
      },
    },
  })
 
  await queryClient.prefetchQuery({
    queryKey: ['dashboard-stats'],
    queryFn: fetchDashboardStats,
  })
 
  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <DashboardStats />
    </HydrationBoundary>
  )
}

// app/dashboard/DashboardStats.tsx (Client Component)
'use client'
import { useQuery } from '@tanstack/react-query'
import { fetchDashboardStats, type DashboardStats } from '@/lib/api'
 
export default function DashboardStats() {
  // 서버에서 채운 캐시를 그대로 활용 — 마운트 시 네트워크 요청 없이 즉시 렌더링
  const { data } = useQuery<DashboardStats>({
    queryKey: ['dashboard-stats'],
    queryFn: fetchDashboardStats,
  })
 
  return (
    <div>
      <p>매출: {data?.revenue.toLocaleString()}원</p>
      <p>주문: {data?.orderCount.toLocaleString()}건</p>
    </div>
  )
}

// app/shop/page.tsx (Server Component)
import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query'
import { Suspense } from 'react'
import ProductList from './ProductList'
import UserGreeting from './UserGreeting'
import { ProductsSkeleton, UserSkeleton } from './skeletons'
import { fetchProducts, fetchUser } from '@/lib/api'
 
export default async function ShopPage() {
  const queryClient = new QueryClient({
    defaultOptions: { queries: { staleTime: 60 * 1000 } },
  })
 
  // await 없이 병렬로 시작 — 두 쿼리가 동시에 서버에서 페칭 시작
  void queryClient.prefetchQuery({
    queryKey: ['products'],
    queryFn: fetchProducts, // 800ms 걸리는 느린 API
  })
  void queryClient.prefetchQuery({
    queryKey: ['user'],
    queryFn: fetchUser, // 50ms 빠른 API
  })
 
  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <Suspense fallback={<UserSkeleton />}>
        <UserGreeting /> {/* 50ms 후 즉시 스트리밍 */}
      </Suspense>
      <Suspense fallback={<ProductsSkeleton />}>
        <ProductList /> {/* 800ms 후 스트리밍, 그 전까지 Skeleton 표시 */}
      </Suspense>
    </HydrationBoundary>
  )
}

// app/shop/UserGreeting.tsx (Client Component)
'use client'
import { useSuspenseQuery } from '@tanstack/react-query'
import { fetchUser, type User } from '@/lib/api'
 
export default function UserGreeting() {
  const { data } = useSuspenseQuery<User>({
    queryKey: ['user'],
    queryFn: fetchUser,
  })
 
  return <p>안녕하세요, {data.name}님!</p>
}

// app/shop/ProductList.tsx (Client Component)
'use client'
import { useSuspenseQuery } from '@tanstack/react-query'
import { fetchProducts, type Product } from '@/lib/api'
 
export default function ProductList() {
  // useSuspenseQuery — 데이터 없으면 suspend, 있으면 즉시 반환
  // data 타입이 항상 non-null로 추론되어 타입 단언 없이도 안전합니다
  const { data } = useSuspenseQuery<Product[]>({
    queryKey: ['products'],
    queryFn: fetchProducts,
  })
 
  return (
    <ul>
      {data.map(product => (
        <li key={product.id}>{product.name}</li>
      ))}
    </ul>
  )
}

// lib/query-client.ts — 요청별 QueryClient 팩토리
import { QueryClient } from '@tanstack/react-query'
 
export function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60 * 1000,
      },
    },
  })
}

// app/layout.tsx
'use client'
import { ReactQueryStreamedHydration } from '@tanstack/react-query-next-experimental'
import { QueryClientProvider } from '@tanstack/react-query'
import { useState } from 'react'
import { makeQueryClient } from '@/lib/query-client'
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  // useState로 인스턴스를 고정 — 매 렌더마다 새로 생성되지 않도록
  const [queryClient] = useState(() => makeQueryClient())
 
  return (
    <QueryClientProvider client={queryClient}>
      <ReactQueryStreamedHydration>
        {children}
      </ReactQueryStreamedHydration>
    </QueryClientProvider>
  )
}

// 어느 Client Component에서든 — 수동 prefetch 없이 스트리밍 SSR 동작
'use client'
import { useSuspenseQuery } from '@tanstack/react-query'
import { fetchProducts, type Product } from '@/lib/api'
 
export function ProductList() {
  const { data } = useSuspenseQuery<Product[]>({
    queryKey: ['products'],
    queryFn: fetchProducts,
  })
  return <ul>{data.map(p => <li key={p.id}>{p.name}</li>)}</ul>
}