Skip to content
Tutorials Center
My learning

Topics

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

React resume and resumeToPipeableStream

Reference for react-dom/server resume and resumeToPipeableStream: finish a partially prerendered page with postponed state, so a cached shell can be sent before dynamic parts.

resume and resumeToPipeableStream continue a render that prerender stopped early. A prerender that is aborted leaves behind two things: an HTML prelude (the shell, with fallbacks for unfinished boundaries) and an opaque postponed object. Later, at request time, you pass the same tree and that object to resume. React renders only the parts that were left out and streams them as a continuation of the prelude.

This is the building block for "partial prerendering": the static shell is built once and served from a CDN, and the dynamic holes are filled per request. Most apps get it through a framework; you call these functions yourself only when you build such a framework or server. The browser cannot run the full flow, because prerender lives in react-dom/static, so the examples below are read-only, with one runnable demonstration of the stream's shape.

JSX
import { prerender } from 'react-dom/static';
import { resume } from 'react-dom/server';

const { prelude, postponed } = await prerender(<App />, { signal });
// later, per request:
const rest = await resume(<App />, postponed);

Try it

Run this in your own project to see the whole flow. It is read-only here.

JSX
import { Suspense, use } from 'react';
import { prerender } from 'react-dom/static';
import { resume } from 'react-dom/server';

const cache = new Map();
function load(key, ms) {
  if (!cache.has(key)) {
    const promise = new Promise((resolve) => setTimeout(() => {
      promise.status = 'fulfilled';
      promise.value = key + '!';
      resolve(promise.value);
    }, ms));
    cache.set(key, promise);
  }
  return cache.get(key);
}

function Slow() {
  return <em>{use(load('a', 300))}</em>;
}
const App = () => (
  <div>
    <h1>Shell</h1>
    <Suspense fallback="fb"><Slow /></Suspense>
  </div>
);

const controller = new AbortController();
setTimeout(() => controller.abort(), 20);
const { prelude, postponed } = await prerender(<App />, {
  signal: controller.signal,
  onError() {},
});
// The prelude is the shell: <div><h1>Shell</h1><!--$?--><template id="B:0"></template>fb<!--/$--></div> plus a script.

await load('a', 300);                 // the data is available now
const rest = await resume(<App />, postponed);
// rest carries only: <div hidden id="S:0"><em>a!</em></div> plus a script.

resumeToPipeableStream is the same call for Node streams, with the callbacks of renderToPipeableStream:

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

const { pipe } = resumeToPipeableStream(<App />, postponed, {
  onShellReady() {
    pipe(response); // continues the document that the prelude started
  },
});

The live example below shows the same two-part shape using only the browser build: the first read is the shell, the rest is what a resume call would write.

The shell and the remainder

Syntax

TypeScript
function resume(
  children: ReactNode,
  postponedState: object,
  options?: {
    nonce?: string;
    signal?: AbortSignal;
    onError?: (error: unknown) => string | void;
  }
): Promise<ReadableStream<Uint8Array> & { allReady: Promise<void> }>;

function resumeToPipeableStream(
  children: ReactNode,
  postponedState: object,
  options?: {
    nonce?: string;
    onShellReady?: () => void;
    onShellError?: (error: unknown) => void;
    onAllReady?: () => void;
    onError?: (error: unknown) => string | void;
  }
): { pipe(destination: NodeJS.WritableStream): void; abort(reason?: unknown): void };
Name Description
children The same React tree that was prerendered. It must produce the same structure for the parts that already exist.
postponedState The postponed value returned by prerender, prerenderToNodeStream, resumeAndPrerender, or a previous aborted run.
options Callbacks and a nonce. Settings that shaped the prelude, such as identifierPrefix, are carried by the postponed state, so you do not repeat them.

Returns: the web version returns a promise of a stream; the Node version returns { pipe, abort }.

Errors: passing null for the postponed state throws a TypeError, because a completed prerender has nothing left to resume. Check postponed !== null first.

Usage notes

  • Serve the prelude first, then write what resume produces to the same response. The two parts form one document.
  • The postponed object is not JSON. Treat it as an in-memory value, or serialize it with a tool that preserves its contents, and only resume it with the same React version that produced it.
  • When nothing was postponed, prerender returns postponed: null. The prelude is the complete page.
  • Wait for the data you need before resuming. In the example the promise is resolved first; the resumed stream otherwise suspends and streams the boundary later as usual.
  • Use the same tree. Changing the component structure between the prerender and the resume breaks the match between state and tree.
  • resumeAndPrerender (in react-dom/static) resumes and produces a new static prelude instead of a stream; it can again return postponed if more is left.
  • Frameworks hide all of this. Reach for it directly only when you control both the build step and the server.