🚀 10. Next.js SSR/SSG 환경의 초기 데이터 주입 (Hydration)

📋 목차

• ☕️ 영철이의 고민: "분명히 Next.js가 짱 빠르다 했는데..."
• 🤔 왜 알아야 하는가: 캐시 사각지대 (Cache Blind Spot)
• 1. 전술 A: initialData (가장 쉽고 직관적인 Prop 전달)
  • 💡 장단점
• 2. 전술 B: `` (진정한 아키텍처의 꽃)
• 📝 배운 내용 점검하기 (Quiz)

"영철 님, 서버 렌더링(SSR) 다 해놓고 왜 브라우저 켜지자마자 데이터를 또 Fetch 하려고 비비적대나요? 수화(Hydration)가 끊겼잖아요!"

☕️ 영철이의 고민: "분명히 Next.js가 짱 빠르다 했는데..."

(금요일 아침, 크롬 퍼포먼스 탭을 켜고 절망하는 영철)

🐣 영철: 아니 리드 님! 저 어제 배운 대로 Next.js App Router 셋업 다 끝냈거든요? 그리고 서버 컴포넌트 안에서 fetch 치니까 화면이 0초 만에 겁나 빡빡하게 렌더링돼서 유저한테 HTML 딱 떨어지는 거 완전 감동했어요!

🦁 영호: 그럼 성공적인데요? 뭐가 불만이시죠?

🐣 영철: 아 그게... 그 서버에서 그린 화면 안에다가 "좋아요 버튼"이나 무한 스크롤 넣으려고 자식 컴포넌트(Client Component)로 조각 파서 놨거든요? 거기 안에 리액트 쿼리 useQuery(['posts'])를 선언하니까, 유저가 페이지 들어와서 화면 보자마자 백그라운드 API를 다시 덮어씁니다! 분명히 그 posts 데이터 위쪽 100줄짜리 부모 서버 주방에서 다 구워서 HTML로 내린 최신 데이터인데, 프론트 엔진 켜지자마자 지가 모르고 다시 가져오잖아요! 서버 부하 과도한 거 아니에요?!

🦁 영호: 아하, 완벽합니다 영철 님. 서버의 주방에서 데이터 열심히 퍼 와서 요리를 구워놓고, 정작 프론트엔드 안의 캐시 금고(QueryCache) 에게는 "서버가 방금 데이터 구워놨으니 너 이거 알고 있어라" 라고 데이터를 주입시켜주질 않았군요.
가장 중요하고 난이도 있는 대미의 장, Hydration (수화) 와 initialData 의 세계에 오신 걸 환영합니다.

🤔 왜 알아야 하는가: 캐시 사각지대 (Cache Blind Spot)

Next.js의 서버 컴포넌트(RSC)에서 부리나케 DB에서 조회해 최신의 완전한 데이터를 다 가져와서 HTML을 그렸다고 가정합시다. 이 화면 껍데기(HTML)를 유저의 모바일 폰으로 빡 던졌습니다.

그런데 그 폰 안에는 React Query라는 독자적인 클라이언트 매니저가 새로 눈을 뜹니다.
대상이 캐시 금고 문을 열어보니...? 텅 비어있습니다.
왜? 서버가 HTML만 줬지, 프론트엔드의 쿼리 클라이언트(메모리) 안에 "내가 무슨 데이터를 썼는지" 주입(Inject) 해주진 않았기 때문이죠.

결국 React Query는 "오 마이 갓, 데이터가 텅 비었네? 내가 다시 API 요청해서 가져와야겠군!" 하며 무의미한 중복 네트워크 트래픽을 유발합니다. 우리는 이를 막기 위해 서버에서 딴 데이터를 클라이언트 캐시로 쏙 집어넣어 주는 초기 데이터 주입 기술 을 마스터해야 합니다.

방법은 크게 2가지입니다.

1. 전술 A: initialData (가장 쉽고 직관적인 Prop 전달)

TkDodo의 아티클 #17을 보면 첫 번째 방법이 제일 쉽습니다.
우리가 RSC(서버 주방) 안에서 데이터를 딱 얻어냈다면, 그걸 자식 조각 컴포넌트(Client Component) 한테 props로 내려찍은 뒤, 쿼리의 initialData 설정 슬롯에 툭 끼워 넣는 방법입니다.

// 📝 app/board/page.tsx (서버 주방 - RSC)
import { getPosts } from '@/api/posts'
import { BoardClient } from './board-client'; // 클라이언트 컴포넌트 (use client)
 
export default async function BoardPage() {
  // 1️⃣ 서버에서 DB를 직접 조회해 데이터를 완벽하게 구워냄
  const postsFromServer = await getPosts();
 
  // 2️⃣ 그 귀한 데이터를 프로퍼티(Prop)로 택배를 싸서 자식에게 던진다!
  return <BoardClient initialPosts={postsFromServer} />
}

// 📝 app/board/board-client.tsx (클라이언트 폰 - CSR)
'use client'
 
import { useQuery } from '@tanstack/react-query';
import { getPosts } from '@/api/posts';
 
export function BoardClient({ initialPosts }: { initialPosts: Post[] }) {
  const { data } = useQuery({
    queryKey: ['posts'],
    queryFn: () => getPosts(),
    // 3️⃣ 🚀 마법의 핵심: "Query야! 내 엄마(서버 주방)가 데이터 싸주셨어! 캐시통에 일단 이거부터 넣고 시작해!"
    initialData: initialPosts,
  });
 
  return (
    <ul> {/* 깜빡임 0%, API 불필요 중복 호출 0배 급증적 성능 */}
      {data.map(post => <li key={post.id}>{post.title}</li>)}
    </ul>
  )
}

💡 장단점

• 장점: 개발자가 직관적으로 이해하기 쉽다.
• 단점: 컴포넌트 트리가 너무나 깁니다. 데이터를 3단계, 4단계 아래 끄트머리에 있는 작은 리스트 컴포넌트한테 전달하려면 Props Drilling 부담이 펼쳐집니다.

2. 전술 B: <HydrationBoundary> (진정한 아키텍처의 꽃)

그래서 탄생한 핵심 전략가 품격 있는 Hydration(Dehydrate/Hydrate) 메커니즘입니다.
서버에서 데이터를 다 딴 다음에, 그 데이터를 스냅샷(DehydratedState)으로 직렬화 시켜서 브라우저로 내려보냅니다.
브라우저에 도착한 dehydrated state는 <HydrationBoundary>를 만나 전역 캐시(QueryClient)에 다시 채워집니다(Hydrate). 이후 클라이언트 컴포넌트는 props로 데이터를 이어받지 않아도 같은 queryKey로 캐시를 읽을 수 있습니다.

Props로 전달 함수처럼 일일이 전달할 필요가 아예 사라지는 겁니다! (오로지 캐시 이름표인 queryKey 만으로 읽어옴)

// 📝 app/board/page.tsx (서버 주방 - RSC)
import { HydrationBoundary, dehydrate, QueryClient } from '@tanstack/react-query'
import { getPosts } from '@/api/posts'
import { BoardClient } from './board-client' // 이건 이제 Prop이 전혀 필요 없지!
 
export default async function BoardPage() {
  // 1️⃣ 이 요청 단 한 번에만 쓰이는 1회용 빈 깡통 생성
  const queryClient = new QueryClient();
 
  // 2️⃣ 미리 데이터를 충분히 당겨서(Prefetch) 서버용 빈 깡통통 캐시 안에 가득 채운다! (queryKey 명심!)
  await queryClient.prefetchQuery({
    queryKey: ['posts'],
    queryFn: getPosts,
  });
 
  return (
    // 3️⃣ dehydrate(깡통 압축기)를 요청해서 클라이언트로 밀어버린다!
    // 전자레인지(Boundary) 가 돌아가는 이 아래쪽(자식) 영역은 이제 신들의 영토다.
    <HydrationBoundary state={dehydrate(queryClient)}>
      <BoardClient />
    </HydrationBoundary>
  )
}

이제 클라이언트 쪽을 볼까요? 눈물이 왈칵 날 만큼 깔끔해집니다.

// 📝 app/board/board-client.tsx (클라이언트 - CSR)
'use client'
 
import { useQuery } from '@tanstack/react-query'
import { getPosts } from '@/api/posts'
 
export function BoardClient() {
  // 🚀 끝!! Prop이 없습니다! initialData도 없습니다!
  // 아까 밖에서 전자레인지(Boundary)가 터질 때 이미 이 브라우저 전역 캐시 안에
  // ['posts'] 라는 키 값으로 캐시가 "아주 꽉 차" 들어갔기 때문입니다.
  const { data } = useQuery({
    queryKey: ['posts'],
    queryFn: () => getPosts()
  });
 
  return <div>{data.length}개 그리기 완료</div>
}

이 패턴이 바로 Next.js App Router와 React Query를 결합시키는 궁극의 엔드게임 아키텍처 입니다. 어떤 자식 컴포넌트 깊숙한 곳에서 useQuery(['posts']) 를 쳐부르더라도 캐시에 이미 꿀데이터가 발라져 있어서 무중복 무로딩 완벽 성능이 나옵니다.

📝 배운 내용 점검하기 (Quiz)

Q. 영철이가 자랑스럽게 <HydrationBoundary> 패턴으로 코드를 작성했는데, 컴포넌트 진입 즉시 백그라운드에서 네트워크 재호출(Refetching) 이 한 번 더 발생하는 걸 목격했습니다. 즉, 서버 렌더링에 성공했음에도 클라이언트에서 한 번 다시 쏘는 기이한 버그인데, 원인이 무엇일까요? 이 옵션의 기본값 철학에 비추어 설명해보세요.

✅ 정답: 서버에서 프리페치하여 넘겨준 데이터(통조림)의 'staleTime'이 0(기본값)이었기 때문입니다.

💡 상세 해설:

• 원리 설명: 서버가 아무리 열심히 prefetchQuery 로 데이터를 채워주고, 클라이언트로 Hydrate(수화) 넘겨줘 봤자 React Query의 신선도(staleTime) 기본값은 0초입니다! 브라우저의 쿼리 대상은 눈을 뜨자마자 "오 데이터 들어있네?(스피너 막음, 일단 화면 그림) 잠깐, 근데 이거 stale(상한 빵) 상태잖아? 당장 서버에 뒷단에서 다시 가서 진짜 최신 맞는지 물어봐야겠다!" 라며 백그라운드 리패칭을 조용히 수행합니다.
• 오답 피드백: "영철 님, 초기 Hydrate 직후 불필요한 뒷단 리패칭(Refetch)를 막고 싶다면, 서버에서 Prefetch 할 때라던가 최상단 QueryClient 인스턴스를 찍어낼 때 staleTime: 60 * 1000 (1분 정도) 의 넉넉한 신선도 유통기한을 강제로 부여해주셔야만 브라우저가 잠시 의심을 거두고 네트워크 로드를 절묘하게 아낍니다!"
• 📌 핵심 기억법: 수화의 마지막 조각은 언제나 넉넉한 유통기한(staleTime) 보장!

📝 마무리 퀴즈

Q1. dehydrate와 HydrationBoundary가 함께 해결하는 문제는 무엇인가요?

✅ 정답: 서버에서 미리 채운 Query Cache 상태를 직렬화해 클라이언트 캐시에 이어 붙여, 같은 queryKey로 즉시 데이터를 읽게 합니다.

💡 상세 해설:
서버가 HTML만 구워도 클라이언트 Query Cache가 비어 있으면 같은 데이터를 다시 가져와야 합니다. dehydrate(queryClient)는 서버 캐시를 전달 가능한 형태로 만들고, HydrationBoundary는 클라이언트에서 그 상태를 복원합니다.

Q2. initialData props 전달보다 Hydration 방식이 커지는 앱에서 유리한 이유는 무엇인가요?

✅ 정답: 깊은 하위 컴포넌트도 props drilling 없이 동일한 queryKey만으로 프리페치된 캐시를 사용할 수 있기 때문입니다.

💡 상세 해설:
initialData는 가까운 컴포넌트에서는 간단하지만 트리가 깊어질수록 전달 경로가 길어집니다. Hydration은 데이터를 Query Cache에 넣어두므로, 소비자는 위치와 관계없이 같은 키로 데이터를 읽습니다. 서버 데이터 계약이 queryKey 중심으로 정리됩니다.

Q3. 영철이의 테스트 타임: SSR에서 서버가 내려준 글 제목과 클라이언트 첫 렌더의 글 제목이 달라 hydration 경고가 났습니다. 가장 먼저 의심할 것은 무엇인가요?

✅ 정답: 서버 프리페치와 클라이언트 useQuery의 queryKey 또는 초기 데이터 기준이 서로 달라 캐시가 같은 데이터로 연결되지 않은 상황입니다.

💡 상세 해설:
Hydration은 서버와 클라이언트가 같은 데이터 계약을 공유할 때 안정적입니다. 키가 조금만 달라도 클라이언트는 빈 캐시로 판단하고 새 요청 또는 다른 데이터를 렌더링할 수 있습니다. 영철이 이제 SSR/hydration을 “HTML 문제”가 아니라 “캐시 계약 문제”로 봐야 합니다.

🐣 영철이의 퇴근 일기

와, 과도한 거 아니야...? 난 또 어제 Next.js 포기하고 전통 SPA로 돌아갈 뻔했는데.
Props 로 넘기려다가 depth 너무 길어져서 울고 있었는데, 서버에서 프리페치(prefetchQuery) 무리하게 넣고 Boundary로 감싸서 브라우저 캐시에 공중 투하(AirDrop) 시켜버리는 방식은 진짜... 기술의 낭만 그 자체다.

💡 오늘의 교훈: "서버 주방에서 맛있는 요리를 픽업했다면 클라이언트 캐시 금고에도 그 레시피를 인수인계(Hydration) 해주자. 그래야 프론트가 불필요하게 API를 또 중복호출하는 문제 상황를 막을 수 있다!"

드디어 Basic 기초 가이드라인 10개가 끝났다. 솔직히 이 10개만 완벽하게 알고 체득해도 어디 가서 서버 상태와 클라이언트 상태를 섞는 실수는 줄일 수 있을 것 같다. 영호 리드 님이 내일부턴 무한 스크롤 같은 Advanced 영역(심화 7강) 할 거라는데, 일단 오늘까진 오늘 배운 기준을 노트에 정리하고 쉬어야겠다