Next.js Streaming이 안 될 때: Suspense와 'use client' 경계 설계법

[서버]                              [브라우저]
 
Layout + 정적 Shell ─────────────→ 즉시 수신, 페인트 시작
                                   (TTFB 최소화)
 
<Suspense fallback={<Skeleton/>}> → Skeleton 렌더링
  <SlowDataComponent/>            → 데이터 준비되면 swap
</Suspense>

// 🚫 이렇게 하면 Streaming 효과가 사라집니다
'use client';
export default function Layout({ children }: { children: React.ReactNode }) {
  return <main>{children}</main>; // 하위 트리 전체가 클라이언트 번들로
}
 
// ✅ 인터랙티브한 리프 컴포넌트에만 선택적으로
export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <main>
      <NavBar /> {/* Server Component — 번들 미포함 */}
      {children}
    </main>
  );
}

// Server Component — await 없이 Promise를 흘려보냅니다
export default function Page() {
  const dataPromise = fetchData(); // await 하지 않음!
  return (
    <Suspense fallback={<Skeleton />}>
      <ClientComponent dataPromise={dataPromise} />
    </Suspense>
  );
}
 
// Client Component — use()로 Suspense 트리거
'use client';
import { use } from 'react';
 
interface Data {
  title: string;
}
 
export function ClientComponent({ dataPromise }: { dataPromise: Promise<Data> }) {
  const data = use(dataPromise); // 준비 안 됐으면 Suspense까지 suspend
  return <div>{data.title}</div>;
}

// app/dashboard/page.tsx (Server Component)
import { Suspense } from 'react';
import { DashboardStats } from './DashboardStats';
import { RecentActivity } from './RecentActivity';
import { StatsSkeleton, ActivitySkeleton } from './Skeletons';
 
export default function DashboardPage() {
  // 두 Promise를 동시에 시작 — await 없이
  const statsPromise = fetchStats();
  const activityPromise = fetchRecentActivity();
 
  return (
    <main>
      {/* Shell — 데이터와 무관하게 즉시 스트리밍 */}
      <h1>대시보드</h1>
      <QuickActions /> {/* Server Component, 데이터 불필요 */}
 
      {/* 독립적인 스트리밍 단위 두 개 — 병렬 처리 */}
      <div className="grid grid-cols-2 gap-4">
        <Suspense fallback={<StatsSkeleton />}>
          <DashboardStats promise={statsPromise} />
        </Suspense>
 
        <Suspense fallback={<ActivitySkeleton />}>
          <RecentActivity promise={activityPromise} />
        </Suspense>
      </div>
    </main>
  );
}

// app/dashboard/DashboardStats.tsx (Client Component)
'use client';
import { use } from 'react';
 
interface StatsData {
  totalUsers: number;
}
 
// 새로고침 핸들러 — 실제 구현에서는 router.refresh()나 revalidatePath로 교체
function refreshStats() {
  window.location.reload();
}
 
export function DashboardStats({ promise }: { promise: Promise<StatsData> }) {
  const stats = use(promise);
 
  return (
    <div className="card">
      <span>{stats.totalUsers.toLocaleString()}</span>
      <button onClick={refreshStats}>새로고침</button>
    </div>
  );
}

// 🚫 CSR Bailout 발생 — 페이지 전체가 클라이언트 렌더링으로 전환
'use client';
export default function SearchPage() {
  const params = useSearchParams(); // 이 한 줄이 문제
  return <div>검색 결과: {params.get('q')}</div>;
}

// ✅ 올바른 패턴 — useSearchParams 로직을 분리하고 Suspense로 감싸기
 
// SearchContent.tsx (Client Component — 작은 단위로 분리)
'use client';
function SearchContent() {
  const params = useSearchParams();
  return <div>검색 결과: {params.get('q')}</div>;
}
 
// page.tsx (Server Component)
import { Suspense } from 'react';
 
export default function SearchPage() {
  return (
    <>
      <h1>검색</h1> {/* 즉시 렌더링 */}
      <Suspense fallback={<div>검색 중...</div>}>
        <SearchContent /> {/* useSearchParams 격리 */}
      </Suspense>
    </>
  );
}

// app/products/[id]/page.tsx
export default function ProductPage() {
  return (
    <>
      {/* LCP 요소 — Suspense 바깥에 배치, 즉시 렌더링 */}
      <ProductHero />
      <ProductInfo />
 
      {/* 첫 번째 스트림 — 리뷰 */}
      <Suspense fallback={<ReviewsSkeleton />}>
        <Reviews />
 
        {/* 두 번째 스트림 — Reviews resolve 이후 fallback 해소 */}
        <Suspense fallback={<RecommendationsSkeleton />}>
          <Recommendations />
        </Suspense>
      </Suspense>
    </>
  );
}

app/
  dashboard/
    loading.tsx      ← 라우트 전환 시 전체 페이지 폴백 (자동 Suspense 래핑)
    page.tsx         ← 개별 섹션은 <Suspense>로 세분화
    components/
      SlowWidget.tsx ← 자체 <Suspense> 경계 보유

// app/dashboard/loading.tsx
export default function Loading() {
  return <DashboardPageSkeleton />; // 라우트 전환 시 표시
}
 
// app/dashboard/page.tsx
export default function DashboardPage() {
  return (
    <div>
      <StaticHeader /> {/* 즉시 렌더링 */}
 
      {/* loading.tsx와 별개로, 섹션별 세분화 */}
      <Suspense fallback={<WidgetSkeleton />}>
        <SlowWidget />
      </Suspense>
    </div>
  );
}