<aside> ❔

서버에서 prefetchInfiniteQuery로 prefetch하는가? ├─ Yes → 로딩 UI를 <Suspense>로 처리할 것인가? │ ├─ Yes → useSuspenseInfiniteQuery ✅ (권장) │ └─ No → useInfiniteQuery (status 분기) └─ No → 클라이언트에서만 fetch하는가? ├─ 로딩 중 UI 필요 → useInfiniteQuery └─ Suspense 경계 사용 → useSuspenseInfiniteQuery ⚠️ (주의)

</aside>

https://tanstack.com/query/latest/docs/framework/react/guides/advanced-ssr

https://tanstack.com/query/latest/docs/framework/react/guides/ssr

상황 1: App Router + 서버에서 prefetch (권장)

Server Component에서 prefetchInfiniteQuery로 데이터를 미리 채운 뒤, Client Component에서 useSuspenseInfiniteQuery사용

// app/projects/page.tsx (Server Component)
import { dehydrate, HydrationBoundary } from '@tanstack/react-query'
import { getQueryClient } from './get-query-client'
import { ProjectList } from './project-list'

export default function ProjectsPage() {
  const queryClient = getQueryClient()
  
  // 클라이언트 컴포넌트에서 Suspense 경계 앞에 실행되는 경우,
  // usePrefetchInfiniteQuery를 사용
  queryClient.prefetchInfiniteQuery({
    queryKey: ['projects'],
    queryFn: ({ pageParam }: { pageParam: number }) =>
      fetch(`/api/projects?cursor=${pageParam}`).then((r) => r.json()),
    initialPageParam: 0,
    getNextPageParam: (lastPage) => lastPage.nextCursor,
    pages: 1, // 첫 페이지만 prefetch
  })

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

// app/projects/project-list.tsx (Client Component)
'use client'
import { useSuspenseInfiniteQuery } from '@tanstack/react-query'

export function ProjectList() {
  const { data, fetchNextPage, hasNextPage } = useSuspenseInfiniteQuery({
    queryKey: ['projects'],
    queryFn: ({ pageParam }: { pageParam: number }) =>
      fetch(`/api/projects?cursor=${pageParam}`).then((r) => r.json()),
    initialPageParam: 0,
    getNextPageParam: (lastPage) => lastPage.nextCursor,
  })

  // data는 항상 정의되어 있음
  return <>{data.pages.map(/* ... */)}</>
}

상황 2: 클라이언트에서만 데이터 fetch

useInfiniteQuery 사용

• 사용자 인터랙션 이후에만 필요한 데이터(예: 모달 내부, 탭 전환 후 로드되는 섹션)
• "Load more" 버튼이 있는 인피니트 스크롤 목록을 서버에서 prefetch하지 않고 그대로 클라이언트에서 처리하는 경우

'use client'
import { useInfiniteQuery } from '@tanstack/react-query'

export function Comments() {
  const { data, status, error, fetchNextPage, hasNextPage, isFetchingNextPage } = 
    useInfiniteQuery({
      queryKey: ['comments'],
      queryFn: ({ pageParam }: { pageParam: number }) =>
        fetch(`/api/comments?cursor=${pageParam}`).then((r) => r.json()),
      initialPageParam: 0,
      getNextPageParam: (lastPage) => lastPage.nextCursor,
    })

  if (status === 'pending') return <Spinner />
  if (status === 'error') return <Error message={error.message} />

  return <>{data.pages.map(/* ... */)}</>
}

https://tanstack.com/query/latest/docs/framework/react/guides/query-cancellation