원문: 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
반응형