Next.js 16 아키텍처 — Turbopack과 Cache Components 깊이 보기

app/
├── layout.tsx          ← 루트 레이아웃 (모든 페이지 공통, 서버 컴포넌트)
├── page.tsx            ← "/" 라우트 진입점
├── loading.tsx         ← Suspense 경계의 폴백 UI
├── error.tsx           ← 에러 경계 (클라이언트 컴포넌트)
├── not-found.tsx       ← 404 처리
├── (marketing)/        ← 라우트 그룹 (URL에 영향 없음)
│   └── about/
│       └── page.tsx    ← "/about"
└── dashboard/
    ├── layout.tsx      ← 중첩 레이아웃 (dashboard 하위 공통)
    ├── page.tsx        ← "/dashboard"
    └── [id]/
        └── page.tsx    ← "/dashboard/:id" 동적 세그먼트

  ┌──────────────────────────────────────────────┐
  │                RootLayout                      │
  │  ┌──────────────────────────────────────────┐ │
  │  │            DashboardLayout                 │ │
  │  │  ┌────────────────┐  ┌──────────────────┐ │ │
  │  │  │  <ErrorBoundary>│  │ <Suspense>       │ │ │
  │  │  │   error.tsx    │  │   loading.tsx    │ │ │
  │  │  │      ▼          │  │      ▼            │ │ │
  │  │  │   page.tsx ────────────▶ 렌더 결과     │ │ │
  │  │  └────────────────┘  └──────────────────┘ │ │
  │  └──────────────────────────────────────────┘ │
  └──────────────────────────────────────────────┘

서버 컴포넌트 (기본)                클라이언트 컴포넌트 ("use client")
────────────────────────           ──────────────────────────────
DB/파일/시크릿 직접 접근  O          브라우저 API/이벤트 핸들러  O
async/await 데이터 패칭   O          useState/useEffect 훅      O
번들에 JS 포함            X          번들에 JS 포함             O
이벤트 핸들러            X          서버 시크릿 접근            X

// server-page.tsx  (서버 컴포넌트)
import ClientShell from './client-shell'
import ServerWidget from './server-widget'

export default async function Page() {
  const data = await fetchData() // 서버에서만 실행
  return (
    <ClientShell>
      {/* ServerWidget은 서버에서 렌더되어 RSC 페이로드로 전달됨 */}
      <ServerWidget data={data} />
    </ClientShell>
  )
}

// client-shell.tsx
'use client'
import { useState } from 'react'

export default function ClientShell({ children }: { children: React.ReactNode }) {
  const [open, setOpen] = useState(false)
  // children(=ServerWidget)은 이미 직렬화된 RSC 트리, 다시 렌더 안 함
  return <div onClick={() => setOpen((v) => !v)}>{open && children}</div>
}

[서버 컴포넌트] ──직렬화 가능한 props──▶ [클라이언트 컴포넌트]
       │                                        ▲
       └──── "use server" 액션 참조 ────────────┘
              (함수 자체가 아닌 참조 ID 전달)

┌─────────┬───────────────────┬──────────────────┬────────────────┐
│ 전략    │ 생성 시점          │ 캐시             │ 적합한 경우     │
├─────────┼───────────────────┼──────────────────┼────────────────┤
│ SSG     │ 빌드 타임          │ CDN 영구         │ 블로그/문서     │
│ ISR     │ 빌드 + 주기 재생성 │ CDN + revalidate │ 상품/뉴스       │
│ SSR     │ 매 요청            │ 캐시 없음(기본)  │ 개인화/실시간   │
│ PPR     │ 정적 셸 + 동적 구멍│ 셸은 CDN, 구멍은 │ 혼합 페이지     │
│         │                   │ 요청 시 스트림   │                │
└─────────┴───────────────────┴──────────────────┴────────────────┘

요청 ──▶ [정적 셸 즉시 전송 (CDN 캐시)]
           ┌────────────────────────────────┐
           │ 헤더 / 네비 / 레이아웃 (정적)    │  ◀── TTFB 매우 빠름
           │  ┌──────────────────────────┐  │
           │  │ <Suspense>               │  │
           │  │   동적 영역 (요청 시)     │  │  ◀── 스트리밍으로
           │  │   예: 사용자 카트, 추천   │  │      이어서 도착
           │  └──────────────────────────┘  │
           │ 푸터 (정적)                     │
           └────────────────────────────────┘

// 함수 단위 캐싱
async function getProducts(category: string) {
  'use cache'
  const res = await fetch(`https://api.example.com/products/${category}`)
  return res.json()
}

// 컴포넌트 단위 캐싱 + 재검증 태그
import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'

async function ProductList({ category }: { category: string }) {
  'use cache'
  cacheLife('hours')        // 캐시 수명 프로파일
  cacheTag(`cat-${category}`) // 태그 기반 무효화
  const products = await getProducts(category)
  return <ul>{/* ... */}</ul>
}

                Cache Components 결정 흐름
  ┌───────────────────────────────────────────────────┐
  │ 컴포넌트/함수에 'use cache' 가 있는가?              │
  └───────────────┬───────────────────┬───────────────┘
            예 (있음)             아니오 (없음)
                 ▼                     ▼
        ┌────────────────┐    ┌────────────────────┐
        │ 정적 셸에 포함  │    │ 동적 데이터 접근?   │
        │ CDN/빌드 캐시   │    │ (cookies/headers)  │
        └────────────────┘    └─────┬──────────┬───┘
                               예 ▼         아니오 ▼
                        ┌──────────────┐  ┌──────────────┐
                        │ 동적 구멍     │  │ 정적 처리 가능 │
                        │ 요청 시 스트림 │  │               │
                        └──────────────┘  └──────────────┘

import { revalidateTag } from 'next/cache'

export async function updateProduct(category: string) {
  'use server'
  await db.update(/* ... */)
  revalidateTag(`cat-${category}`) // 해당 태그가 붙은 캐시만 무효화
}

   브라우저
     │  GET /dashboard/42
     ▼
 ┌─────────────────────────────────────────────────────────┐
 │                     Edge / CDN 계층                       │
 │  정적 셸 캐시 적중?  ──예──▶ 즉시 셸 반환 (스트림 시작)    │
 │         │ 아니오                                          │
 └─────────┼───────────────────────────────────────────────┘
           ▼
 ┌─────────────────────────────────────────────────────────┐
 │                  Next.js 서버 런타임                      │
 │  1) 라우트 매칭 (app/dashboard/[id]/page.tsx)            │
 │  2) middleware 실행 (인증/리다이렉트)                     │
 │  3) 레이아웃 → 페이지 RSC 렌더 시작                       │
 │     ├─ 'use cache' 영역 → 데이터 캐시 조회                │
 │     └─ 동적 영역 → 데이터 패칭(fetch/DB)                  │
 │  4) RSC 페이로드 생성 + HTML 스트리밍                     │
 └─────────┬───────────────────────────────────────────────┘
           ▼
 ┌─────────────────────────────────────────────────────────┐
 │                  데이터 / 캐시 계층                       │
 │  Data Cache (fetch 결과)  ·  Full Route Cache (RSC)      │
 │  외부 DB / API / 파일 시스템                              │
 └─────────────────────────────────────────────────────────┘
           ▼
   브라우저: HTML 스트림 수신 → 하이드레이션 → 상호작용 가능

┌────────────────────────────────────────────────────────────┐
│  1. Router Cache (클라이언트 메모리)                         │
│     - 방문한 라우트의 RSC 페이로드를 브라우저에 보관         │
│     - 뒤로가기/prefetch 시 즉시 렌더                         │
├────────────────────────────────────────────────────────────┤
│  2. Full Route Cache (서버 빌드/런타임)                      │
│     - 정적 라우트의 RSC + HTML 결과                          │
├────────────────────────────────────────────────────────────┤
│  3. Data Cache (서버, 영속)                                  │
│     - fetch 결과 / 'use cache' 함수 결과                     │
│     - cacheLife / revalidateTag 로 제어                      │
├────────────────────────────────────────────────────────────┤
│  4. Request Memoization (단일 요청 수명)                     │
│     - 같은 요청 내 동일 fetch 중복 제거                      │
└────────────────────────────────────────────────────────────┘

        webpack (기존)                Turbopack (Rust)
  ──────────────────────────    ──────────────────────────
  JS 기반 단일 스레드 위주       Rust 멀티코어 병렬 처리
  전체 그래프 재계산 경향        함수 단위 증분 캐싱
  큰 앱일수록 시작 느림          요청한 라우트만 온디맨드 컴파일
  HMR 점진적                     변경분만 최소 재계산

   파일 변경 (button.tsx)
          │
          ▼
   ┌──────────────────────────────┐
   │ 의존성 그래프에서 영향 추적    │
   │ button.tsx → toolbar.tsx →    │
   │             page.tsx          │
   └──────────────┬───────────────┘
                  ▼
   영향받은 노드만 무효화 후 재계산
   (그래프의 나머지는 캐시 그대로)
                  │
                  ▼
   HMR 패치를 브라우저로 전송

// 변경된 패턴
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  return <div>{id}</div>
}

[ ] 클라이언트 컴포넌트에 서버 전용 모듈(fs, db)을 import 하지 않았는가
[ ] 서버→클라이언트 props가 모두 직렬화 가능한가 (함수/클래스 제외)
[ ] 'use client' 경계를 너무 위쪽에 둬서 번들이 비대해지지 않았는가
[ ] 동적 데이터(cookies/headers) 접근 영역을 Suspense로 감쌌는가
[ ] revalidateTag 의 태그 문자열이 cacheTag 와 정확히 일치하는가
[ ] 환경 변수 중 NEXT_PUBLIC_ 접두사 여부를 혼동하지 않았는가

나쁜 예                          좋은 예
─────────────                   ─────────────
RootLayout ("use client")       RootLayout (server)
   └─ 전부 클라이언트 번들          └─ Page (server)
                                      └─ LikeButton ("use client")
                                         ← 상호작용 잎만 클라이언트

/dashboard/[id]
 ├─ Layout (정적, 'use cache')          ← 네비/사이드바
 ├─ ProfileHeader (동적: cookies 사용)   ← 사용자별, Suspense 구멍
 ├─ StatsPanel ('use cache', cacheLife) ← 5분 캐시, 공용 통계
 └─ ActivityFeed (동적: 실시간)          ← 스트리밍, Suspense 구멍