🚀 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) 메커니즘입니다.
서버에서 데이터를 다 딴 다음에, 그 데이터를 통조림(DehydrateState)으로 꽁꽁 깡통 압축 시켜서 브라우저로 내려보냅니다.
폰에 도착한 깡통은 <HydrationBoundary> 라는 전자레인지를 만나서 펑! 하고 터지면서 전역 캐시 금고(QueryClient)의 구석구석 모든 방방곡곡으로 그 냄새(데이터)를 퍼트려버립니다(Hydrate).

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']) 를 쳐부르더라도 캐시에 이미 꿀데이터가 발라져 있어서 무중복 무로딩 완벽 성능이 나옵니다.

🐣 영철이의 퇴근 일기

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

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

드디어 Basic 기초 가이드라인 10개가 끝났다. 솔직히 이 10개만 완벽하게 알고 체득해도 어디 가서 스파게티 소스 통으로 뒤엎는 민폐는 절대 안 끼칠 거 같다. 영호 리드 님이 내일부턴 무한 스크롤 같은 Advanced 영역(심화 7강) 할 거라는데, 일단 오늘까진 대가리에 박힌 짜릿함 즐기면서 꿀잠자야지 ㅋㅋㅋㅋ. 🐶

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

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

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

💡 상세 해설:

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