Skip to content
Tutorials Center
My learning

Topics

React Reference ยท react-dom/server and Static APIs

React renderToReadableStream function

Reference for react-dom/server renderToReadableStream: stream HTML as a web ReadableStream on Deno, Bun, edge runtimes and in the browser, with allReady and abort signals.

renderToReadableStream renders a React tree to a web ReadableStream of bytes. It is the streaming server renderer for runtimes built on web standards: Deno, Bun, Cloudflare Workers, Vercel Edge and other fetch-style handlers. The Node.js equivalent is renderToPipeableStream.

Unlike the Node function it returns a promise. The promise resolves once the shell (the part outside waiting Suspense boundaries) is ready, and rejects if the shell fails. The stream it resolves to carries an extra property, allReady, a promise that settles when every boundary has finished.

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

const stream = await renderToReadableStream(<App />, {
  bootstrapScripts: ['/main.js'],
});
return new Response(stream, { headers: { 'Content-Type': 'text/html' } });

Try it

Wait for everything with allReady

The first result is the shell with a fallback plus a later chunk that fills it in. After awaiting allReady the content is already inline: <section><!--$--><em>loaded</em><!--/$--></section>. That is the right choice for crawlers and static output.

Giving up with an abort signal

When the signal fires, the stream closes. The boundary stays as its fallback (with a marker <!--$?-->), and the browser takes over after hydration. onError is called with the abort reason.

Syntax

JSX
const stream = await renderToReadableStream(reactNode, options?);
TypeScript
function renderToReadableStream(
  children: ReactNode,
  options?: {
    identifierPrefix?: string;
    namespaceURI?: string;
    nonce?: string;
    bootstrapScriptContent?: string;
    bootstrapScripts?: (string | { src: string; integrity?: string; crossOrigin?: string })[];
    bootstrapModules?: (string | { src: string; integrity?: string; crossOrigin?: string })[];
    importMap?: { imports?: Record<string, string>; scopes?: Record<string, Record<string, string>> };
    progressiveChunkSize?: number;
    signal?: AbortSignal;
    onError?: (error: unknown, info: { componentStack?: string }) => string | void;
    onHeaders?: (headers: Headers) => void;
  }
): Promise<ReadableStream<Uint8Array> & { allReady: Promise<void> }>;
Name Description
reactNode The tree to render, typically the whole <html> document.
signal An AbortSignal. Aborting stops waiting; unfinished boundaries stay as fallbacks for the client to complete.
onError Called for every error. The returned string becomes the error digest sent to the client.
onHeaders Receives a Headers object with early hints, if any, before the body starts.
Other options Script and ID options as for the Node version; see Bootstrap scripts and options.

Returns: a promise of a ReadableStream with an allReady promise on it.

Errors: the promise rejects when the shell throws. Catch it and return an error response. Errors inside a Suspense boundary do not reject; they are reported through onError.

Usage notes

  • Rendering a full document adds the doctype. If the root is an <html> element, the stream starts with <!DOCTYPE html> for you. renderToString does not do that.
  • The stream is bytes. Decode with TextDecoder, or hand the stream to new Response(stream), which is what most frameworks do.
  • Cancel what you do not read. If the client disconnects, cancel the stream (or abort the signal) so React stops rendering for nobody.
  • Status codes must be decided before the first byte. Keep a flag set from onError and read it after the await. It catches errors from the shell render; errors in boundaries that finish later arrive too late to change the status.
  • Use signal as a timeout. AbortSignal.timeout(5000) works as the value.
  • allReady for bots. Await it before returning the response to a crawler or when generating static files.
  • The Node build also exports this function, but Node projects normally prefer renderToPipeableStream.
  • The browser build exports it too, which is how the examples on this page run.