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.
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.
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:
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.
Syntax
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
resumeproduces 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,
prerenderreturnspostponed: 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(inreact-dom/static) resumes and produces a new static prelude instead of a stream; it can again returnpostponedif more is left.- Frameworks hide all of this. Reach for it directly only when you control both the build step and the server.