Next.js 15/16 Partial Prerendering 실전 가이드 — 정적 셸과 동적 스트리밍으로 FCP를 최소화하는 Suspense 경계 설계

// next.config.ts (Next.js 15)
const nextConfig = {
  experimental: {
    ppr: 'incremental', // 앱 전체가 아닌 라우트별 선택 적용
  },
};
 
export default nextConfig;

// app/products/[id]/page.tsx
export const experimental_ppr = true; // 이 라우트에만 PPR 활성화
 
export default function ProductPage() {
  return (
    <main>
      {/* 정적 셸: 빌드 타임에 CDN으로 */}
      <ProductHeader />
      <ProductImages />
 
      {/* 동적 홀: 요청 타임에 스트리밍 */}
      <Suspense fallback={<PriceSkeleton />}>
        <RealtimePrice />
      </Suspense>
    </main>
  );
}

// next.config.ts (Next.js 16)
const nextConfig = {
  cacheComponents: true, // experimental.ppr 대신 안정화된 설정
};
 
export default nextConfig;

// components/ProductHeader.tsx (Next.js 16)
'use cache'; // 이 컴포넌트의 결과는 정적 캐시에 포함됩니다
import { cacheLife, cacheTag } from 'next/cache';
 
export async function ProductHeader({ productId }: { productId: string }) {
  // 캐시 유효기간: 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks'
  cacheLife('days');
 
  // 태그 등록 → 이후 revalidateTag()로 이 컴포넌트만 선택적 무효화 가능
  cacheTag(`product-${productId}`);
 
  const product = await fetch(`/api/products/${productId}`).then(r => r.json());
  return <header>{product.name}</header>;
}

// app/products/[id]/page.tsx (Next.js 15)
export const experimental_ppr = true;
 
export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>; // Next.js 15부터 params는 Promise
}) {
  const { id } = await params;
 
  return (
    <main className="product-page">
      {/* 정적 셸: 빌드 타임에 CDN으로 배포 */}
      <Breadcrumb />
      <ProductImages productId={id} />
      <ProductDescription productId={id} />
      <ShippingInfo />
 
      {/* 동적 홀: 요청마다 서버에서 병렬 스트리밍 */}
      <Suspense fallback={<PriceSkeleton />}>
        <RealtimePrice productId={id} />
      </Suspense>
 
      <Suspense fallback={<StockSkeleton />}>
        <StockStatus productId={id} />
      </Suspense>
 
      <Suspense fallback={<CartSkeleton />}>
        <CartButton productId={id} />
      </Suspense>
 
      <Suspense fallback={<RecommendationSkeleton />}>
        <PersonalizedRecommendations productId={id} />
      </Suspense>
    </main>
  );
}

// components/ProductImages.tsx — 정적 셸 컴포넌트
export async function ProductImages({ productId }: { productId: string }) {
  // 기본 fetch는 캐시됨 → 빌드 타임에 정적 셸에 포함
  const images = await fetch(`/api/products/${productId}/images`).then(r =>
    r.json()
  );
 
  return (
    <div className="product-images">
      {images.map((img: { src: string; alt: string }) => (
        <img key={img.src} src={img.src} alt={img.alt} />
      ))}
    </div>
  );
}

// components/RealtimePrice.tsx — 동적 홀 컴포넌트
export async function RealtimePrice({ productId }: { productId: string }) {
  // cache: 'no-store' → 매 요청마다 새로 페치 → Suspense 안에서 동적 처리
  const price = await fetch(`/api/products/${productId}/price`, {
    cache: 'no-store',
  }).then(r => r.json());
 
  return <div className="price">{price.amount.toLocaleString()}원</div>;
}

// app/dashboard/page.tsx
export const experimental_ppr = true;
 
export default function DashboardPage() {
  return (
    <DashboardLayout> {/* 정적: 사이드바, 헤더, 그리드 컨테이너 */}
 
      {/* 아래 네 홀은 각각 독립적으로 병렬 시작됩니다 */}
      <Suspense fallback={<KpiSkeleton />}>
        <KpiMetrics />      {/* DB 쿼리 200ms */}
      </Suspense>
 
      <Suspense fallback={<ChartSkeleton />}>
        <RevenueChart />    {/* 외부 API 450ms */}
      </Suspense>
 
      <Suspense fallback={<TableSkeleton />}>
        <RecentOrders />    {/* DB 쿼리 120ms */}
      </Suspense>
 
      <Suspense fallback={<AlertSkeleton />}>
        <SystemAlerts />    {/* 내부 API 80ms */}
      </Suspense>
 
    </DashboardLayout>
  );
}

// app/home/page.tsx
export const experimental_ppr = true;
 
export default function HomePage() {
  return (
    <>
      {/* 정적: 로그인 여부와 무관한 공개 콘텐츠 */}
      <HeroSection />
      <FeaturedContent />
      <PublicNav />
 
      {/* 동적: 로그인 상태 및 사용자별 콘텐츠 */}
      <Suspense fallback={<UserNavSkeleton />}>
        <UserNavBar />       {/* 내부에서 cookies()로 세션 확인 */}
      </Suspense>
 
      <Suspense fallback={<NotificationSkeleton />}>
        <Notifications />    {/* 사용자별 알림 */}
      </Suspense>
    </>
  );
}

// ❌ 잘못된 예: Suspense 바깥의 UserGreeting이 cookies()를 호출 → 페이지 전체 동적 처리
export default function Page() {
  return (
    <main>
      <StaticHero />
      <UserGreeting /> {/* cookies() 호출 → 정적 셸 무효화 */}
    </main>
  );
}
 
// ✅ 올바른 예: Suspense로 감싸 해당 영역만 동적 처리
export default function Page() {
  return (
    <main>
      <StaticHero />
      <Suspense fallback={<UserGreetingSkeleton />}>
        <UserGreeting />
      </Suspense>
    </main>
  );
}

// ❌ fallback 없는 Suspense — 레이아웃 이동(CLS) 발생 가능
<Suspense>
  <DynamicWidget />
</Suspense>
 
// ✅ 스켈레톤으로 공간을 예약하고 시각적 피드백 제공
<Suspense fallback={<WidgetSkeleton />}>
  <DynamicWidget />
</Suspense>

// ❌ 하나의 큰 Suspense — 모든 위젯이 가장 느린 API를 기다림
<Suspense fallback={<DashboardSkeleton />}>
  <KpiMetrics />
  <RevenueChart />  {/* 가장 느린 외부 API */}
  <RecentOrders />
</Suspense>
 
// ✅ 독립적인 Suspense — 각 위젯이 준비되는 즉시 화면에 등장
<Suspense fallback={<KpiSkeleton />}><KpiMetrics /></Suspense>
<Suspense fallback={<ChartSkeleton />}><RevenueChart /></Suspense>
<Suspense fallback={<TableSkeleton />}><RecentOrders /></Suspense>