React 18 스트리밍: renderToPipeableStream 작동 방식

React 18 이전에는 서버 측 렌더링에 동기식인 renderToString을 사용했습니다. React는 브라우저로 HTML을 보내기 전에 전체 컴포넌트 트리를 문자열로 렌더링합니다. 어떤 컴포넌트든 데이터를 로드하면 첫 번째 바이트가 사용자에게 도달하기 전에 서버는 모든 데이터가 준비될 때까지 기다려야 합니다.

React 18에서는 컴포넌트 트리를 HTML 청크 스트림으로 렌더링하는 renderToPipeableStream을 도입했습니다. 모든 준비가 끝날 때까지 기다리는 대신 React는 트리의 각 부분이 완료되는 대로 HTML을 전송하므로 브라우저가 표시 가능한 콘텐츠를 즉시 렌더링하기 시작할 수 있습니다.

renderToPipeableStream은 두 메서드인 pipe(writable)과 abort()를 포함하는 객체를 반환합니다. pipe는 Node.js Writable 스트림(일반적으로 HTTP 응답)을 받아 해당 스트림으로 HTML 전송을 시작합니다. abort()는 스트림을 취소하며, 요청이 취소되거나 시간 제한을 초과했을 때 사용합니다.

스트림은 대기 중인 Suspense 경계에 의해 차단되지 않는 모든 콘텐츠인 HTML 셸로 시작합니다. 여기에는 문서 헤드, 탐색 메뉴, 푸터, 레이아웃 공통 UI와 동기적으로 사용 가능한 콘텐츠가 포함됩니다. 셸은 데이터에 의존하는 컴포넌트가 해결되기 전에 즉시 스트리밍됩니다.

데이터를 기다리는 Suspense 경계 내부의 컴포넌트는 처음에는 대체 UI(예: 로딩 스피너)로 스트리밍됩니다. React는 나중에 대체 UI를 해결된 콘텐츠로 바꾸는 스크립트 태그를 전송하므로 클라이언트에서 셸을 다시 렌더링하지 않아도 됩니다.

renderToPipeableStream에 bootstrapScripts: ['/static/js/client.js']를 전달하면 스트림 끝에 스크립트 태그를 삽입하도록 React에 지시할 수 있습니다. 브라우저는 이 번들을 로드하고 hydrateRoot를 호출하여 서버에서 렌더링된 DOM에 React의 이벤트 처리기를 연결합니다.

onShellReady는 HTML 셸(대기 중인 Suspense 경계 외부의 모든 콘텐츠)을 전송할 준비가 되었을 때 실행됩니다. 이때 pipe(res)를 호출하는 것이 올바릅니다. 단, 스트리밍이 HTTP 상태 코드를 확정하므로 pipe를 호출하기 전에 HTTP 상태 코드와 응답 헤더를 설정해야 합니다.

스트리밍은 pipe()를 호출하는 즉시 시작되므로, 모든 res.setHeader 또는 res.statusCode 할당은 pipe 호출 전에 이루어져야 합니다. 일반적인 패턴은 onShellReady 콜백에서 상태 코드 200과 Content-Type: text/html을 설정한 다음, 바로 이어서 pipe(res)를 호출하는 것입니다.

셸 렌더링이 완료되기 전에 복구할 수 없는 오류가 발생하면 onShellError가 실행됩니다. 예를 들어 최상위 컴포넌트가 Suspense 경계 바깥에서 오류를 발생시키는 경우입니다. 이때는 응답의 일부만 스트리밍할 수 없으므로 오류 페이지로 리디렉션하거나 정적인 오류 HTML 문서를 보내야 합니다.

모든 Suspense 경계를 포함한 전체 리액트 트리가 해결되면 onAllReady가 실행됩니다. 검색 엔진 크롤러와 소셜 미디어 링크 미리보기 도구에는 스트리밍하지 않고 완성된 HTML을 보내는 것이 좋습니다. 요청이 봇에서 온 것인지 확인한 다음 onShellReady 대신 onAllReady에서 pipe(res)를 호출하세요.

Suspense 경계 내부에서 오류가 발생하면 onError가 실행됩니다. 해당 경계가 오류 UI로 대체되는 동안에도 리액트는 페이지의 나머지 부분을 계속 스트리밍할 수 있습니다. onError를 사용해 사용자에게 스트리밍을 중단하지 않고 관측성 파이프라인에 오류를 기록하세요.

파이핑을 시작할 때 onShellReady 대신 onAllReady를 사용해야 하는 경우는 언제일까요?

renderToPipeableStream은 Node.js 서버를 위한 React 18의 스트리밍 SSR 기본 기능입니다. onShellReady를 통해 HTML 셸을 즉시 스트리밍하고, 데이터가 해결되면 Suspense 경계를 채우며, bootstrapScripts를 통해 클라이언트를 하이드레이션합니다. 봇과 크롤러에는 onAllReady를 사용하고, 치명적인 오류에는 onShellError를 사용하며, 항상 pipe()를 호출하기 전에 HTTP 헤더를 설정하세요.