스트리밍 SSR

스트리밍 SSR이란

전통적인 SSR은 서버가 HTML 문서 전체를 완성한 뒤에 응답한다. 느린 쿼리가 하나만 있어도 페이지 전체가 그만큼 늦는다. 스트리밍 SSR은 HTTP 청크 전송(chunked transfer encoding)으로 준비된 부분부터 조각조각 보낸다. 서버가 나머지를 만드는 동안 브라우저는 이미 받은 HTML을 그리기 시작한다.

React에서는 <Suspense> 경계가 조각을 나누는 단위다. 경계 바깥은 먼저 보내고, 경계 안쪽은 fallback을 먼저 보냈다가 준비되면 진짜 내용으로 바꿔 끼운다.

발전 과정

스트리밍은 선택 기능에서 기본 동작으로 바뀌었다.

React 19에서 옛 Node 스트림 API인 renderToNodeStream·renderToStaticNodeStream과 클라이언트의 ReactDOM.hydrate는 제거됐다. 옛 코드에서 보면 각각 renderToPipeableStream(정적 결과가 필요하면 onAllReady까지 기다린다)과 hydrateRoot로 바꾼다.

React 문서는 renderToString·renderToStaticMarkup을 레거시(Legacy) API로 분류한다. 스트리밍 API보다 기능이 제한되기 때문이다. 핵심 원리(Suspense 경계, 선택적 hydration, HTTP 상태 코드 제약)는 React 18 때와 같다. 달라진 점은 렌더링 시점이다. 요청마다 처음부터 렌더링하고 스트리밍하던 것이 정적 부분은 미리 만들고 동적 부분만 이어서 스트리밍하는 방식으로 진화했다.

동작 흐름

flowchart TB
  n0["요청"] --> n1["첫 청크: 정적 껍데기(static shell)<br/>#lt;head#gt;·CSS·JS 링크, 레이아웃, 내비게이션,<br/>Suspense fallback 자리 #lt;template id=#quot;B:0#quot;#gt;"]
  n1 -->|"브라우저가 바로 그리고 CSS·JS 다운로드 시작"| n2["다음 청크: 컴포넌트 payload (hydration용)"]
  n2 --> n3["+1s: 경계 0 완료<br/>#lt;div hidden id=#quot;S:0#quot;#gt;완성된 HTML#lt;/div#gt; + 교체 스크립트"]
  n3 --> n4["+3s: 경계 1 완료<br/>#lt;div hidden id=#quot;S:1#quot;#gt;…#lt;/div#gt; + 교체 스크립트"]

• 교체 스크립트는 인라인이라 JS 번들이나 hydration을 기다리지 않고 바로 fallback을 바꾼다.
• 형제 Suspense 경계끼리는 서로를 막지 않는다. 먼저 끝난 것부터 들어온다.
• 중첩 경계는 바깥이 끝나야 안쪽 fallback이 보이므로 단계적으로 드러난다.

무엇이 좋아지나

주의할 점

1. 상태 코드와 헤더는 첫 청크에서 확정된다

스트리밍이 시작되면 200 OK가 이미 나간 상태다. 그 뒤에 notFound()가 나오면 404로 바꿀 수 없어서 Next.js는 noindex 메타 태그를 넣고, redirect()는 클라이언트 측 이동으로 바뀐다. 진짜 404나 리다이렉트가 필요하면 Suspense 경계와 느린 await보다 앞에서 판단하거나 proxy·설정 리다이렉트로 처리한다.

2. Suspense를 아무 데나 두면 LCP가 늦어진다

LCP 요소(히어로 이미지, 주요 제목)가 경계 안에 있으면 교체 스크립트가 실행될 때까지 그려지지 않는다. LCP 요소는 경계 바깥·위에 둔다. 느린 네트워크나 바쁜 CPU에서는 React가 예상하지 못한 경계의 fallback을 보여 줄 수도 있으니, 필요 없는 경계는 만들지 않는다.

3. fallback 크기가 다르면 CLS가 생긴다

스켈레톤을 실제 콘텐츠와 같은 크기로 만들거나, 감싸는 영역에 최소 높이를 준다.

4. 중간 계층이 버퍼링하면 효과가 사라진다

DevTools Network 탭에서 문서 요청의 TTFB가 짧고 Content Download가 길면 실제로 스트리밍되고 있는 것이다.

5. 봇은 스트리밍을 받지 않을 수 있다

HTML만 읽는 크롤러를 위해 Next.js는 user agent로 봇을 가려 generateMetadata가 끝날 때까지 기다렸다가 <head>를 채운다. DOM을 실행하는 브라우저·크롤러는 스트리밍 메타데이터를 받는다.

Next.js에서 쓰는 법

export default function Dashboard() {
  return (
    <div>
      <h1>Dashboard</h1> {/* 정적 껍데기: LCP 후보는 바깥에 */}
      <Suspense fallback={<RevenueSkeleton />}>
        <Revenue /> {/* async 서버 컴포넌트 */}
      </Suspense>
      <Suspense fallback={<OrdersSkeleton />}>
        <RecentOrders />
      </Suspense>
    </div>
  )
}

• loading.js는 페이지 전체를 감싸는 Suspense다. 데이터 없이는 아무것도 그릴 수 없는 페이지에 쓴다. 나머지는 경계를 데이터를 쓰는 곳 가까이 둔다.
• cookies()·params·fetch를 레이아웃 꼭대기에서 await하면 그 아래 전체가 동적이 된다. Promise를 그대로 내려 보내고 필요한 컴포넌트가 경계 안에서 푼다(클라이언트 컴포넌트라면 use 훅). 레이아웃에서 기다리면 왜 하위 구획이 모두 막히는지는 App Router 노트의 「렌더링을 막는 위치」에 있다.
• Cache Components를 쓰면 경계 없이 동적 데이터에 접근할 때 빌드 오류(blocking route)가 난다. 경계를 강제하는 셈이다.

정리

• 스트리밍 SSR은 "SSR이냐 CSR이냐"의 이분법을 깨고 한 페이지 안에서 빠른 부분과 느린 부분을 따로 보낸다.
• 원리는 React 18에서 정해졌다. renderToString만 쓰는 방식은 레거시다.
• 지금의 흐름은 정적 껍데기를 최대한 키우고(캐시) Suspense 경계는 동적 데이터 바로 옆에 두는 것이다.
• 대가도 있다. 상태 코드를 나중에 바꿀 수 없고, 프록시·CDN 버퍼링에 약하며, 경계를 잘못 두면 LCP·CLS가 나빠진다.

어디서 렌더링할지보다 어디에 Suspense 경계를 둘지가 렌더링 전략의 핵심 결정이 되었다.

관련 노트: SPA와 CSR·SSR, Next.js App Router의 내비게이션과 데이터 가져오기, Next.js를 쓰는 이유, use 훅과 리액트 비동기 처리, 브라우저 렌더링 과정