엣지에서의 스트리밍 SSR

서버가 HTML을 스트리밍하면 브라우저는 완성된 문서를 기다리는 대신 콘텐츠를 조각별로 받아 렌더링합니다. 따라서 사용자는 헤더, 탐색 메뉴, 주요 영역처럼 페이지에서 보이는 부분을 먼저 보고 상호작용할 수 있으며, 데이터에 의존하는 느린 영역은 계속 로드할 수 있습니다.

renderToReadableStream에 bootstrapScripts를 전달하면 클라이언트 측 JS 번들이 있는 위치를 React에 알려줍니다. React는 스트림 끝에 스크립트 태그를 삽입하므로 브라우저가 번들을 로드하고 hydrateRoot를 호출할 수 있으며, 각 영역의 스트리밍이 끝나는 대로 페이지가 상호작용 가능해집니다.

React의 스트리밍은 컴포넌트 트리를 독립적으로 스트리밍할 수 있는 영역으로 나누는 Suspense 경계에 의존합니다. 데이터가 준비되기를 기다리는 Suspense 경계 내부의 컴포넌트는 던져진 프라미스로 인해 먼저 자리 표시자로 스트리밍되고, 이후 준비가 완료되면 실제 콘텐츠가 스트리밍됩니다.

onShellReady 콜백은 Suspense 경계 바깥의 모든 요소로 이루어진, 일시 중단되지 않은 HTML 셸이 스트리밍할 준비를 마쳤을 때 실행됩니다. 이 시점에 HTTP 상태 코드와 응답 헤더를 설정한 다음 pipe(res)를 호출하거나 ReadableStream에서 읽기 시작하는 것이 올바릅니다.

HTTP 상태 코드와 헤더는 응답 본문이 시작되기 전에 전송해야 합니다. 스트리밍은 onShellReady에서 시작되므로 오류 처리 로직(상태를 500으로 설정하거나 리디렉션하는 작업)도 셸이 흐르기 전에 실행되어야 합니다. 스트리밍이 시작되면 상태 코드는 더 이상 변경할 수 없습니다.

onShellError는 셸이 준비되기 전에 치명적인 오류가 발생하면 실행됩니다. 예를 들어 Suspense 경계 바깥의 최상위 컴포넌트에서 오류가 발생한 경우입니다. 이때는 셸이 전혀 스트리밍되지 않으므로 정적 오류 페이지를 응답하거나 오류 라우트로 리디렉션해야 합니다.

onError는 Suspense 경계 내부에서 복구 가능한 오류가 발생하면 실행됩니다. React는 페이지의 나머지 부분을 계속 스트리밍할 수 있으며, 오류가 발생한 경계는 오류 대체 UI를 렌더링합니다. 스트림을 중단하지 않고 관측 플랫폼에 오류를 기록하려면 onError를 사용하십시오.

Suspense 경계의 데이터를 가져오는 데 너무 오래 걸리면 셸은 그대로 스트리밍하고 클라이언트에서 해당 경계를 하이드레이션하도록 하십시오. 시간 초과를 구현하십시오. 5초 후에도 경계가 완료되지 않으면 스트림에서 abort()를 호출하고, 그러면 클라이언트가 useEffect를 통해 직접 데이터를 가져옵니다.

워커 런타임은 ReadableStream을 Response 본문으로 직접 전달합니다. 클라우드플레어의 인프라는 리액트가 생성하는 각 청크를 전체 문서에 버퍼링하지 않고 사용자의 브라우저로 전달합니다. 따라서 요청이 도착한 뒤 몇 밀리초 안에 HTML의 첫 바이트가 엣지 PoP를 떠납니다.

renderToReadableStream은 중단 제어 함수를 반환합니다. 요청이 취소되면(사용자가 다른 페이지로 이동한 경우) abort()를 호출하여 리액트가 계속 렌더링하고 데이터를 처리하지 않도록 할 수 있습니다. 이렇게 하면 고아 요청에 불필요한 연산을 수행하는 일을 막고 워커의 CPU 사용량을 제한할 수 있습니다.

엣지 스트리밍을 사용하면 전체 지연 시간은 다음과 같습니다. 5ms(가장 가까운 PoP로 요청 전송) + 2ms(워커 콜드 스타트) + 8ms(셸 렌더링) = 첫 바이트까지 15ms입니다. 나머지 페이지가 백그라운드에서 계속 스트리밍되는 동안 사용자의 브라우저는 셸에서 LCP 요소를 렌더링합니다.

스트리밍 SSR 중에 onShellReady 콜백은 정확히 언제 실행되나요?

엣지에서의 스트리밍 SSR은 HTML을 청크 단위로 전달하여 셸을 즉시 보내 FCP와 LCP를 개선합니다. Suspense 경계는 트리를 독립적으로 스트리밍할 수 있는 섹션으로 나눕니다. onShellReady는 스트림 연결을 시작하라는 신호이므로 이를 호출하기 전에 상태 코드를 설정하십시오. onShellError는 치명적인 실패를 처리하고 onError는 복구 가능한 실패를 처리하며, abort()는 취소된 요청에 대한 불필요한 작업을 방지합니다.