Next.js App Router와 TanStack Query의 구조적 복잡성과 해결 패턴

카테고리

프로그래밍/소프트웨어 개발

서브카테고리

웹 개발

대상자

Next.js와 TanStack Query를 사용하는 프론트엔드 개발자 (중급~고급)

• 난이도: SSR과 CSR 통합 문제 이해 필요, React Query 및 Next.js App Router 기초 지식 요구

핵심 요약

• Next.js App Router의 SSR 방식과 TanStack Query의 CSR 캐시 시스템 간 충돌 발생
• HydrationBoundary + prefetchQuery + dehydrate를 통해 서버 패칭 데이터를 클라이언트 캐시에 하이드레이션
• 중복 요청 방지, UX 개선, 네트워크 성능 최적화 효과

섹션별 세부 요약

1. 문제 개요

• Next.js App Router는 SSR과 Server Components 기반으로 데이터를 서버에서 먼저 패칭하여 초기 HTML에 포함
• TanStack Query는 CSR 기반으로 클라이언트에서 useQuery() 호출 시 데이터를 새로 요청
• 서버에서 패칭한 데이터가 클라이언트 캐시에 반영되지 않아 중복 요청 및 로딩 상태 발생

2. 구조적 충돌 지점

• 서버에서 prefetchQuery()로 데이터 패칭 → dehydrate()로 캐시 상태 직렬화
• 클라이언트에서 HydrationBoundary로 하이드레이션 → useQuery()가 캐시를 인식
• TTFB(Time To First Byte) 단축 및 SEO 최적화 가능

3. 해결 패턴: HydrationBoundary 기반 프리패칭

• prefetchQuery()로 서버에서 데이터 미리 가져오기
• dehydrate()로 캐시 상태를 HTML에 포함
• 클라이언트에서 HydrationBoundary로 캐시 복원 → useQuery() 재요청 방지
• 코드 예시:

```tsx

// app/page.tsx

import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query'

const queryClient = new QueryClient()

await queryClient.prefetchQuery({ queryKey, queryFn: fetchData })

return (

{/ ClientComponent /}

)

```

4. SSR 최적화 전략

• 3단계 통합 프로세스:

1. 서버에서 prefetchQuery()로 데이터 패칭
2. dehydrate()로 캐시 상태 직렬화
3. 클라이언트에서 HydrationBoundary로 캐시 복원

• 요청 워터폴 문제 해결: 초기 마크업에 데이터 포함 → 클라이언트에서 추가 요청 없이 렌더링

결론

• HydrationBoundary + prefetchQuery + dehydrate 트리플 사용을 통해 SSR과 CSR 통합 문제 해결
• 중복 요청 방지 및 UX 개선을 위해 서버에서 데이터 패칭 후 클라이언트 캐시 복원 필수
• Next.js App Router + TanStack Query 통합 시 반드시 적용해야 하는 핵심 패턴