번역 자료 / / 2025. 5. 28. 06:45

[react 번역] renderToReadableStream API

원문: https://react.dev/reference/react-dom/server/renderToReadableStream


renderToReadableStream

renderToReadableStream은 React 트리를 Readable Web Stream으로 렌더링합니다.

const stream = await renderToReadableStream(reactNode, options?)
  • 레퍼런스
    • renderToReadableStream(reactNode, options?)
  • 사용법
    • React 트리를 Readable Web Stream으로 HTML 렌더링하기
    • 로딩되는 대로 추가 콘텐츠 스트리밍하기
    • shell에 포함할 내용 지정하기
    • 서버에서 크래시 로깅하기
    • shell 내부/외부 에러 복구하기
    • 상태 코드 설정하기
    • 다양한 에러를 다르게 처리하기
    • 크롤러/정적 생성 시 모든 콘텐츠가 로드될 때까지 대기하기
    • 서버 렌더링 중단하기

이 API는 Web Streams 환경(Deno, Edge 등)에서 사용합니다. Node.js에서는 renderToPipeableStream을 사용하세요.


레퍼런스

renderToReadableStream(reactNode, options?)

React 트리를 HTML로 Readable Web Stream에 렌더링하려면 renderToReadableStream을 호출하세요.

import { renderToReadableStream } from 'react-dom/server';

async function handler(request) {
  const stream = await renderToReadableStream(<App />, {
    bootstrapScripts: ['/main.js']
  });
  return new Response(stream, {
    headers: { 'content-type': 'text/html' },
  });
}

클라이언트에서는 hydrateRoot를 호출해 서버에서 생성된 HTML을 인터랙티브하게 만듭니다.

파라미터

  • reactNode: HTML로 렌더링할 React 노드(JSX 등). 전체 문서를 나타내야 하므로, App 컴포넌트는 <html> 태그를 렌더링해야 합니다.
  • options(선택): 스트리밍 옵션 객체
    • bootstrapScriptContent: 인라인 <script> 태그에 들어갈 문자열
    • bootstrapScripts: <script> 태그로 삽입할 스크립트 URL 배열. hydrateRoot를 호출하는 스크립트를 포함해야 함
    • bootstrapModules: <script type="module">로 삽입할 모듈 스크립트 URL 배열
    • identifierPrefix: useId로 생성되는 ID의 접두사(서버/클라이언트 동일해야 함)
    • namespaceURI: 루트 네임스페이스 URI. 기본값은 HTML, SVG/MathML 등은 별도 지정
    • nonce: CSP를 위한 스크립트 허용 난수값
    • onError: 서버 에러 발생 시 호출되는 콜백(기본값: console.error)
    • progressiveChunkSize: 청크 크기(기본값: 내부 휴리스틱)
    • signal: AbortSignal로 서버 렌더링을 중단할 수 있음

반환값

  • Promise로, shell 렌더링에 성공하면 Readable Web Stream을 반환합니다.
  • shell 렌더링에 실패하면 Promise가 reject됩니다. 이때 fallback shell을 출력할 수 있습니다.
  • 반환된 stream에는 allReady 프로퍼티가 있어, shell과 모든 추가 콘텐츠 렌더링이 끝나면 resolve됩니다. 크롤러/정적 생성 시 await stream.allReady로 모든 데이터가 준비될 때까지 대기할 수 있습니다.

사용법

React 트리를 Readable Web Stream으로 HTML 렌더링하기

import { renderToReadableStream } from 'react-dom/server';

async function handler(request) {
  const stream = await renderToReadableStream(<App />, {
    bootstrapScripts: ['/main.js']
  });
  return new Response(stream, {
    headers: { 'content-type': 'text/html' },
  });
}

App 컴포넌트는 전체 문서(<html> 태그 포함)를 반환해야 하며, bootstrap 스크립트 경로도 지정해야 합니다.

shell에 포함할 내용 지정하기

export default function App() {
  return (
    <html>
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <link rel="stylesheet" href="/styles.css"></link>
        <title>My app</title>
      </head>
      <body>
        <Router />
      </body>
    </html>
  );
}

React는 doctype과 bootstrap <script> 태그를 HTML 스트림에 자동으로 삽입합니다.


에러 처리 및 고급 사용법

  • shell 내부/외부에서 발생하는 에러에 따라 onError, Suspense fallback 등으로 복구할 수 있습니다.
  • 상태 코드 설정, 크롤러/정적 생성 시 stream.allReady 사용, 서버 렌더링 중단(signal) 등 다양한 고급 옵션을 지원합니다.

출처: https://react.dev/reference/react-dom/server/renderToReadableStream

반응형
  • 네이버 블로그 공유
  • 네이버 밴드 공유
  • 페이스북 공유
  • 카카오스토리 공유