Skip to content

resumeAndPrerender behavior doesn't seem to match documentation #8755

Open

Description

@leo60228

Summary

The documentation for resumeAndPrerender suggests using the returned prelude as a response body, but this stream is not a full HTML document.

Page

https://react.dev/reference/react-dom/static/resumeAndPrerender

Details

The page only includes a snippet, rather than a runnable example, but an adjusted version of the resume example demonstrates that it does not render a full page: https://codesandbox.io/p/sandbox/react-dev-forked-ws9htk

It's possible this is a bug in the implementation, but I can't find clear evidence of what the intention was, and no tests seem to exercise this path. Given the current behavior, I don't understand what correct usage of this function would look like.

Activity

  1. mhdnihadot commented on Nov 16, 2026

    @mhdnihadot

    I reproduced this with react-dom 19.3.1. After an aborted prerender, the prelude returned by resumeAndPrerender contains only the postponed content: the hidden <div id="S:0"> segments plus the $RC scripts. It has no <!DOCTYPE>, <html> or shell. It's byte-for-byte identical to what resume() returns for the same postponed state. So new Response(prelude) as in the docs example serves a broken page. You need to send the original prerender prelude first and append this output after it.

    One more thing on the same page: the example passes bootstrapScripts, but resumeAndPrerender ignores it (no /main.js in the output), the same as the resume caveat says.

    If this is the intended behavior, I'm happy to send a docs PR that:

    • updates the intro and Returns section to say prelude is the continuation, not a full document
    • changes the example to append it after the stored prerender prelude
    • removes bootstrapScripts from the example and adds the same caveat resume has

    Or is the full-document behavior the intended one and this is an implementation bug?

  2. pawannyadav05 commented on Nov 21, 2026

    @pawannyadav05

    Fixes #8755

    Summary

    Clarifies in the resumeAndPrerender reference documentation that the returned prelude Web Stream is not necessarily a standalone, complete HTML document if rendering was postponed or aborted.

    Problem

    The documentation for resumeAndPrerender previously stated:

    prelude: a Web Stream of HTML. You can use this stream to send a response in chunks, or you can read the entire stream into a string.

    And showed a code snippet returning new Response(prelude) directly.
    This caused confusion for developers who expected the prelude stream to always yield a fully formed HTML document. In reality, with partial pre-rendering (PPR), if components postpone or abort during prerendering, the prelude only contains the static shell and resolved segments. Developers who return prelude directly as the response body without combining it with a resumed stream end up serving an incomplete document.

    Solution

    • Updated the return description for prelude in resumeAndPrerender.md to explicitly state that the stream contains the rendered shell and resolved segments, and is not necessarily a complete HTML document if postponed or aborted.
    • Added guidance that delivering a complete response requires combining the static prelude with the resumed stream or ensuring root tags without unhandled postponed boundaries.

    Changes

    • src/content/reference/react-dom/static/resumeAndPrerender.md: Updated the prelude return value description.

    PR opened in #8768.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions