🧊 Next.js 심화 2장: `use cache`와 부분 캐싱 (Next.js 15+ 최신 트렌드)

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🏗️ 비유로 먼저 이해하기
• 🧩 use cache 디렉티브: 함수 수준의 영구 동결 🟢
• 🌱 컴포넌트 단위 캐싱 (Cache Components) 🟡
• 🛡️ PPR (Partial Pre-Rendering): 정적 껍데기 + 동적 속살 🔴
• 💥 에러 해결 카탈로그
• 🏁 이번에 배운 내용 총정리
• 📝 마무리 퀴즈
• 🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 15분 (전체) / 핵심 파트만: 8분

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 영철(신입): "Next.js 15+로 넘어오니 기본 fetch가 예전처럼 알아서 오래 캐시된다고 가정하면 안 되겠더라고요. 무거운 통계 컴포넌트는 재사용하고 싶은데, 어디까지 캐시해도 안전한지 코드에서 명확히 표현할 방법이 있을까요?"
• 영호(리드): "그때 보는 게 Cache Components와 'use cache'예요. next.config.ts에서 cacheComponents: true를 켜고, 함수나 컴포넌트 안에서 재사용 가능한 계산만 캐시 대상으로 선언합니다. 단, cacheLife, cacheTag, updateTag까지 같이 설계해야 운영에서 안전해요."

🗺️ 이 문서의 흐름
Next 15의 캐시 선언형 시대 → use cache의 스코프 적용법 → 대망의 PPR (절반만 화석 만들기) 기술

🎯 이 문서를 다 읽으면 할 수 있는 것

• 무거운 써드파티 SDK나 직접 짠 슬로우 쿼리 함수 자체에 'use cache' 지시자를 달아 컴포넌트 레벨의 캐싱 아키텍처를 세밀하게 직조할 수 있다.
• 정적인 껍데기 안에 실시간 데이터를 품은 <Suspense> 구역을 섞어, PPR 아키텍처의 혁명적인 TTFB(0.1초 초기 로딩)를 구현할 수 있다.

🤔 왜 알아야 하는가

심화 1장에서 우리는 캐시 수명을 이해하지 못하면 화면이 낡은 데이터를 보여줄 수 있다는 걸 봤어. 최신 Next.js에서는 Cache Components 모델이 강화되면서 "재사용 가능한 조각을 개발자가 명시적으로 선언하고, 그 조각의 수명과 무효화 경로도 함께 적는다" 는 방향이 중요해졌어.

이 새로운 선언적 캐싱 시대에서 프론트 시니어들에게 가장 핫한 무기가 바로 심화 2장의 주제인 'use cache' 예약어와 PPR(부분 렌더링) 이야.

이걸 모르면 너는 Next 15 세상에서 모든 페이지 컴포넌트를 비싼 CPU 렌더링으로 돌리다가 클라우드 요금 문제을 맞고 회사에서 짐을 싸게 될지도 몰라. 화면 전체 단위가 아닌, "내가 원하는 조각"만 얼려버리는 최신 핀셋 기법을 지금부터 마스터하자.

🏗️ 비유로 먼저 이해하기

🧒 5살에게 설명한다면? (영호의 빙결 마법책)

❌ 과거 14버전 (눈보라 광역 마법)
마을 전체(페이지 통째로)에 눈보라를 내려서 온 동네를 얼려버렸어. 다 꽁꽁 얼어붙어서 장사는 빠른데 눈사람이 안 움직여서 답답했어.

✅ 현재 15버전 (핀셋 빙결 마법 'use cache')
이제 영호 리드가 요술 지팡이 하나를 들고 다녀.
"얍!" 하고 지팡이('use cache')로 치는 특정 상자(함수, 컴포넌트)만 꽁꽁 얼어붙어서 (캐시 서버에 저장), 다음번 부를 땐 연산 0초 만에 완제품이 튀어나와! 마을 사람들(나머지 동적 요소)은 춥지 않고 실시간으로 막 뛰어다닐 수 있지.

🧩 use cache 디렉티브: 함수 수준의 영구 동결 🟢

'use client' 나 'use server' 처럼 파일, 컴포넌트, 함수 스코프 최상단에 붙이는 지시어야. 최신 공식 문서 기준으로는 Cache Components 기능이며, next.config.ts에 cacheComponents: true를 켠 뒤 사용한다.

먼저 프로젝트 설정에 캐시 컴포넌트를 명시한다.

// next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  cacheComponents: true,
}
 
export default nextConfig

이 설정을 켜야 'use cache', cacheLife, cacheTag를 하나의 캐시 모델로 설명할 수 있다.

상황: 무거운 통계 분석 함수 (fetch가 아님!)

영철이가 짜놓은 5초짜리 월간 집계 쿼리가 있어. fetch로 호출하는 외부 API가 아니라, Node.js 환경에서 DB 클라이언트(Prisma 등)와 무거운 계산을 직접 수행하는 함수라고 가정해보자.

// app/lib/stats.ts
// fetch가 아니므로 "어떤 수명으로 재사용할지"를 별도로 선언해야 한다.
export async function getHeavyMonthlyStats(year: number, month: number) {
  const rawData = await db.query(...);
  const result = heavyCPUCalculate(rawData); // 여기서 5초간 끙끙댐...
  return result;
}

✅ 빙결 부적 붙이기 ('use cache')

캐시 가능한 입력과 갱신 조건이 분명하다면 함수 내부에서 캐시 정책을 같이 선언한다.

// app/lib/stats.ts
import { cacheLife, cacheTag } from 'next/cache'
 
export async function getHeavyMonthlyStats(year: number, month: number) {
  'use cache';
  cacheLife('hours');
  cacheTag(`monthly-stats-${year}-${month}`);
 
  const rawData = await db.query(...);
  const result = heavyCPUCalculate(rawData);
  return result;
}

'use cache'의 캐시 키에는 함수 위치, 빌드 ID, 직렬화 가능한 인자 등이 들어간다. 그래서 같은 year, month로 호출할 때 재사용할 수 있지만, 관리자 저장 액션에서는 같은 태그를 updateTag나 revalidateTag로 갱신해야 한다.

[캐시의 부작용 (무효화)]
이거 심화 1장의 React.cache() (1초 단발성 지우개) 랑 착각하면 안 돼!
React.cache()는 같은 요청 안의 중복 호출을 줄이는 메모이제이션이고, 'use cache'는 요청을 넘어 재사용될 수 있는 캐시 정책이야.
즉, 누군가가 어드민 페이지에서 매출 기준을 갱신한다면 저장 액션에서 같은 태그를 갱신해야 유저가 낡은 통계를 오래 보지 않는다.

🌱 컴포넌트 단위 캐싱 (Cache Components) 🟡

함수 말고, HTML 태그를 뿜어내는 '리액트 컴포넌트(export default function...)' 자체도 통째로 얼려버릴 수 있어!

상황: DB에서 가져온 1만 개 목록 그리기

// app/components/MegaList.tsx
 
// 🧊 이 컴포넌트 덩어리가 뿜어내는 "HTML 구조" 결과물 자체를 통째로 얼려버린다!
export default async function MegaList({ categoryId }: { categoryId: string }) {
  'use cache';
 
  // 1만 개 레코드를 가져와서 수만 개의 <li> 태그로 조립하는 거대한 CPU 연산
  const data = await db.getItems(categoryId);
 
  return (
    <ul>
      {data.map(item => <li key={item.id}>{item.name}</li>)}
    </ul>
  )
}

이제 page.tsx 등 아무 곳에서나 저 <MegaList /> 를 수백 번 렌더링하도록 호출해봐도, 서버는 HTML 태그 문자열 조립을 아예 생략하고 디스크 어딘가 캐시 창고에서 꺼낸 완성품 텍스트 덩어리를 0.01초 만에 브라우저에 배달해줘.
프론트 서버 요금을 획기적으로 낮추는 2026 트렌드의 핵심 기법이지.

🛡️ PPR (Partial Pre-Rendering): 정적 껍데기 + 동적 속살 🔴

자, 이제 궁극의 퀘스트. "Next.js 렌더링 최정점의 기술"로 넘어가자.

모순되는 요구사항

기획자가 왔어.
"개발자님! 우리 쇼핑몰 메인의 상단 GNB(메뉴)랑 전체 틀은 아무도 안 건드리니까 빠딱빠딱 광속(Static)으로 뜨게 해주시고요.
대신 한가운데 박혀 있는 [사용자 장바구니 영역]은 방문객 이름이랑 개인 쿠키마다 전부 다르게(Dynamic) 떠야 해요!"

심화 1장에서 배웠지? "단 한 줄의 실시간 쿠키라도 읽으면 그 페이지의 화석(Static)은 영원히 훼손되고 전체가 SSR(Dynamic)로 강등된다" 고!

✅ PPR (부분 사전 렌더링) 이라는 이단아

Vercel 천재들이 이걸 극복해냈어!
우리가 가이드 7장에서 배운 <Suspense> 구멍 뚫기 기술과 결합 된 괴물 사양이야.

// app/page.tsx
// ⚠️ 이 페이지 안에 실시간 정보(쿠키 등)가 있지만 난 절대 속도 강등을 당하지 않을 테다!
 
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import StaticHeader from './StaticHeader'
 
// 1. 여기서 동적 (매 접속마다 달라지는 개인화) 데이터를 사용하는 컴포넌트 덩어리를 분리한다!
async function PersonalCart() {
  const token = (await cookies()).get('token'); // 💣 원래라면 전체 라우트를 동적으로 만들 수 있는 요청 시점 API!!
  const cartInfo = await fetchCart(token);
  return <div>내 장바구니: {cartInfo.count}개</div>
}
 
 
// 2. 전체 조합하는 메인 컴포넌트 레이아웃
export default function HomePage() {
  return (
    <main>
      {/* 🌟 여기는 빌드 타임에 평생 보존되는 화석(Static)으로 깡깡 얼어서 0.1초 만에 서빙됨! */}
      <StaticHeader />
 
      {/* 🌟 동적 구역을 Suspense 캡슐로 격리해 가둬버렸다! */}
      <Suspense fallback={<div>장바구니 로딩중...</div>}>
        <PersonalCart />
      </Suspense>
 
      {/* 🌟 여기도 Static! */}
      <Footer />
    </main>
  )
}

[마법의 작동 원리 (PPR 캐싱 결합)]

1. 빌드 명령(next build) 시, 넥스트 봇이 트리를 순회하다가 Suspense 캡슐을 만나면 "아하! 이 구멍(Hole) 안쪽은 동적 구역니까 내가 건드리면 안 되겠군. 대신 캡슐 바깥의 껍데기 레이아웃들은 모조리 정적 화석 스켈레톤(Static)으로 잔뜩 구워두자!" 하고 부분 화석을 만들어내.
2. 유저가 접속하면? 가운데 동적 구역은 fallback으로 남겨둔 채 정적 셸(GNB + Footer + 장바구니 로딩중 글씨)이 빠른 TTFB로 먼저 전달된다.
3. 그와 동시에 캡슐 안쪽의 살살 녹는 동적 장바구니 컴포넌트가 뒤늦게 쿠키를 까보고 서버 연산을 마친 뒤 그 빈 구멍을 채우러 Stream 전송된다.

이것이 Next.js가 밀어붙이는 궁극의 아키텍처, 껍데기는 화석으로! 속살은 무한한 동적 데이터로! "Partial Pre-Rendering(PPR)" 의 실체야.

💥 에러 해결 카탈로그

에러 메시지가 뜨면 Ctrl+F로 검색해봐.

❌ 'use cache'를 붙였는데 캐시가 적용되지 않음

원인: next.config.ts에 cacheComponents: true가 없거나, 캐시 함수의 인자가 직렬화할 수 없는 값(Class 인스턴스, 함수, Symbol 등)을 포함한 경우가 많다.
해결책: 설정을 먼저 확인하고, 캐시 스코프에는 직렬화 가능한 인자만 넘긴다. 요청 시점 값(cookies, headers)이 필요하다면 캐시 밖에서 읽어 인자로 전달하거나, 정말 사용자별 캐시가 필요한 경우 별도 지시어를 검토한다.

❌ Suspense 캡슐을 잘 씌웠는데 빌드해보면 자꾸 속살까지 다 까발려진 채 전체 페이지가 Dynamic으로 강등당해버려요 ㅠㅠ

원인: 아주 흔한 실수.
위험한 코드(const t = cookies().get())를 캡슐의 바깥(부모)인 page.tsx 내부 스코프에 덩그러니 선언해 두고, 그걸 속살 컴포넌트의 Props로 내려보내는 우를 범했기 때문.
부모가 요청 시점 API에 노출된 순간 부모의 껍데기도 함께 오염되어 영원히 화석 기능을 상실한다.
해결책: 무조건 속살 컴포넌트 스코프 내부 안쪽으로 cookies()나 리퀘스트 헤더 읽기 명령문을 통째로 격리/이전시켜야 PPR이 동적 구역을 제대로 분리한다.

🏁 이번에 배운 내용 총정리

💡 시니어의 멘탈 모델
14버전까지는 fetch 에 달린 파라미터 옵션에 목을 맸다면, 15버전부터는 함수 묶음이나 UI 조각 덩어리 자체를 핀셋으로 집어 얼려버리는 우아한 시대에 진입했다. 컴포넌트 안에서 어디 부분까지 정적인지 캡슐 구멍 뚫기(Suspense)만 잘해도 당신은 신의 경지!

📝 마무리 퀴즈

Q1. 'use cache'를 함수 안에 붙였을 때 캐시 키를 결정하는 핵심 입력은 무엇인가?

✅ 정답: 함수의 인자와 캐시 가능한 실행 컨텍스트다.

💡 상세 해설: 'use cache'는 "이 함수의 결과를 재사용해도 된다"고 선언하는 디렉티브다. 같은 인자로 호출했을 때 같은 결과를 반환해야 안전하다. 요청마다 달라지는 cookies(), headers() 같은 값에 기대는 로직은 캐시 범위에 넣으면 안 된다. 영호가 보는 기준은 순수성이다. 입력이 같으면 결과도 같다고 말할 수 있어야 한다.

Q2. 영숙이 월간 추천 상품을 어드민에서 바꿨다. 'use cache'로 캐시한 getMonthlyPicks()가 있다면 어떤 보강이 필요할까?

✅ 정답: cacheTag('monthly-picks')처럼 태그를 붙이고, 저장 액션에서 revalidateTag 또는 즉시 일관성이 필요하면 updateTag로 갱신한다.

💡 상세 해설: 캐시는 만드는 순간보다 깨는 순간이 더 중요하다. 최신 공식 문서 기준으로 Cache Components에서는 cacheLife로 시간 정책을, cacheTag로 온디맨드 갱신 대상을 선언한다. revalidateTag는 stale-while-revalidate 성격으로 배경 갱신에 적합하고, 사용자가 방금 쓴 결과를 즉시 봐야 하는 read-your-own-writes 상황은 updateTag가 더 맞다.

Q3. 영철이의 테스트 타임: 대시보드 상단 설명, 인기 글 목록, 내 알림 카운트를 한 페이지에 배치한다. 'use cache'를 어디에 적용해야 할까?

✅ 정답: 설명과 인기 글처럼 사용자와 무관하고 일정 시간 재사용 가능한 부분에만 적용한다.

💡 상세 해설: 내 알림 카운트는 세션과 실시간성에 묶여 있으므로 캐시하면 다른 사용자의 값이 섞이거나 낡은 숫자가 보일 수 있다. 반대로 마케팅 설명 문구나 인기 글 목록은 cacheLife('hours') 같은 정책과 태그 갱신을 붙이면 비용을 줄일 수 있다. PPR과 함께 쓸 때도 정적 셸과 동적 구멍의 책임을 분리하는 게 핵심이다.

🐣 영철이의 퇴근 일기

오늘은 'use cache'를 "빠르게 해주는 주문"이 아니라 "재사용해도 되는 약속"으로 다시 배웠다. 캐시를 함수나 컴포넌트 단위로 붙일 수 있다는 건 편하지만, 그만큼 내가 어떤 데이터를 고정시키는지 더 분명히 알아야 했다.

💡 "캐시 가능한 조각은 사용자 입력에서 독립적이고, 갱신 이벤트를 설명할 수 있어야 한다."

다음 코드 리뷰에서는 'use cache'가 보이면 세 가지를 확인하겠다. 요청 시점 API를 읽는지, cacheLife가 실제 신선도 요구와 맞는지, 관리자 저장이나 서버 액션에서 태그 갱신이 연결되어 있는지. 이제 성능을 올리는 제안도 운영자가 데이터를 바꾸는 순간까지 포함해서 말할 수 있을 것 같다.

🔗 더 알아보기

• Next.js Docs: Rendering / PPR (Partial Pre-Rendering)