Upgrading to React 18 on the server

[gaearon]

Overview

Upgrading to React 18 on the server has the following steps:

• Upgrade to the latest React 18 release
• Optionally, switch from renderToString to renderToPipeableStream to unlock the new features

React 18 includes architectural improvements to React server-side rendering (SSR) performance described in New SSR Suspense Architecture. These improvements are substantial and are the culmination of several years of work.

API Changes

Previously, React did not support Suspense on the server at all. This is changing in React 18, but there are different levels of support depending on which API you use:

• renderToString: Keeps working (with limited Suspense support).
• renderToNodeStream: Deprecated (with full Suspense support, but without streaming).
• renderToPipeableStream: New and recommended (with full Suspense support and streaming).

Existing API: renderToString(React.Node): string

This API continues to work. It doesn’t support new features so we recommend switching to renderToPipeableStream . However, it’s not deprecated, so you can keep using renderToString.

In React 18, we’re adding very limited <Suspense> support to renderToString. Previously, trying to use <Suspense> with it threw an error. Starting in React 18, if you suspend during renderToString, we will mark the nearest Suspense boundary as "client-rendered" and immediately emit the fallback HTML. Then, we will retry rendering its content on the client after the JS has loaded. Concretely, this means that if you wrap your app in a top-level <Suspense> boundary and you suspend during rendering, your app effectively opts out of server rendering.

This change shouldn't affect existing apps because suspending on the server previously did not work at all. However, if you tried to render <Suspense> on the client only by conditionally suspending, you may now get mismatches leading to content being removed from the DOM. Conditionally rendering different content on the server and the client’s first render is not (and has not been) supported in React in general.

Note: This behavior isn’t very useful, but it’s the best we can do because renderToString is synchronous. It can't “wait” for anything. This is why we recommend the new renderToPipeableStream instead.

Deprecated API: renderToNodeStream(React.Node): Readable

We will be deprecating renderToNodeStream completely in React 18—using it will warn. This was the first streaming API that we added, but it was very underpowered (it could not wait for data). It's also not commonly used. It will work in 18, including the new Suspense features described below, but it will buffer the entire content until the end of the stream. In other words, it will no longer do streaming. This makes its purpose confusing, which is why we’re deprecating it.

We are replacing it with renderToPipeableStream.

Recommended API: renderToPipeableStream(React.Node, Options): Controls

This will be the recommended API going forward. It has all the new features:

• Full built-in support for <Suspense> (which integrates with data fetching)
• Code splitting with lazy without flashes of "disappearing" content
• Streaming of HTML with "delayed" content blocks "popping in" later

In the latest Alpha versions, you can get it from:

import { renderToPipeableStream } from 'react-dom/server';

Unlike renderToString(), it involves more wiring. We've prepared an example demo of how you could change your code from using renderToString() to renderToPipeableStream(). We will provide more detailed documentation later, but the demo should get you started.

To learn more about what this API unlocks, read New SSR Suspense Architecture.

This API is not yet integrated with data fetching. The general Suspense mechanism should work, but we don't have a recommendation yet for how to transfer data from the server to the client to prepopulate the cache. We expect to provide more guidance on this in the future.

There are also some questions you'll want to experiment with. For example, how to deal with the <title> tags. Since this is a true streaming API, you might not have an "ideal" title by the time you start streaming. There are various solutions you could try, and we're curious to hear if you find something that works well for you as you test this API in your app and experiment with different approaches.

Other APIs

There are a few other APIs related to generating static markup. Their behavior mirrors the main APIs:

• renderToStaticMarkup: Keeps working (with limited Suspense support).
• renderToStaticNodeStream: Deprecated (with full Suspense support, but without streaming).

The new recommended API for them that mirrors renderToPipeableStream has not been added yet.

[chantastic]

Concretely, this means that if you wrap your app in a top-level boundary and you suspend during rendering, your app effectively opts out of server rendering.

if you tried to render different content on the server and on the client (which is not supported) by conditionally suspending, this will not work anymore

Love the concrete clarity of this statements.

[liuyenwei]

This API continues to work for synchronous work, but it will no longer throw when using Suspense. Starting in React 18, if you suspend during renderToString, we will mark the nearest Suspense boundary as "client-rendered" and immediately emit the fallback HTML. Then, we will retry rendering its content on the client after the JS has loaded.

Do these changes also apply to the other existing render* APIs (renderToNodeStream, renderToStaticMarkup, etc)? I'm assuming yes but figured it'd be good to clarify 😄

[gaearon]

Yeah. The streaming API will be getting a replacement though. (Although the old one will keep working.) I’ll add more details soon.

[gaearon]

This page has been updated. We have added details to this page about the new APIs, and some existing ones. We also wrote up a deep dive on the architectural improvements to SSR in React 18. These improvements are substantial and are a culmination of several years of work: #37.

[gaearon]

Added further edits to this page — corrected some mistakes about renderToNodeStream and clarified the part about breaking changes.

[gaearon]

Another update: pipeToNodeWritable moved to react-dom/server. react-dom/unstable-fizz has been deleted.

Also, renderToString is now implemented on top of the new internals, so in theory there could be bugs. (Tell us if you find any!) We'll be hooking it up to our production soon.

[ad1992]

This is awesome 🔥, and the example is also very helpful 👌. I am very excited to try this out!
Looks like there is a typo 👇🏻

renderToString renderToNodeStream: Deprecated (with limited Suspense support).

[gaearon]

Yes, thank you. Edited.

[devknoll]

Can pipeToNodeWritable ever actually do any piping without calling startWriting first? If not, should this API get renamed/restructured a bit (e.g. so the stream can be passed in with startWriting instead)?

[gaearon]

The purpose of startWriting is to let you render immediately but delay flushing the tree until you have enough of a shell ready. I'm not sure what you're proposing — can you show the code?

[devknoll]

To be clear I'm bikeshedding. Anyway:

pipeToNodeWritable(res, <Foo />, {/* options */}).startWriting() vs render(<Foo />, {/* options */}).pipe(res) (as an example). The thought being that it looks like pipeToNodeWritable does the rendering and startWriting does the writing/piping, so renaming them accordingly 😄

As an added benefit, it would more closely match the shape of the createRoot API for 💥 SYNERGY💥

[gaearon]

Ah I see. What should happen if you call pipe more than once?

[devknoll]

Ideally that would be supported, and it could stream the current state (when pipe started). In practice, I realize that the implementation consumes and mutates state as streaming progresses so a throw new Error('pipe called after writing already started') seems fine.

That said, it occurs to me that the existing API does match createRoot, as least as far as providing the destination upfront. But the name pipeToNodeWritable is still a bit confusing since nothing actually gets piped.

[wardpeet]

@devknoll I had the same question and asked it here #66. Writable is not pipe-able, the best option you can do with the current implementation is to use A Duplex/Transform stream.

[devknoll]

We can use the onReadyToStream and onComplete callbacks to adjust the timing of the startWriting call to decide whether we generate "dynamic" HTML that includes e.g. <script> tags to update the DOM as suspense boundaries resolve on the server.

But what if we want to generate both types of HTML for the same tree? Not all User Agents will execute JavaScript, but may still need a final DOM. That means that during build time (or in the background, for e.g. Next's Incremental Static Regeneration) we may want want to render and cache both versions. But as of today, that would mean calling pipeToNodeWritable twice, which would mean suspense boundaries get resolved twice, data gets fetched twice, etc, and creates the possibility that the trees may diverge from each other, as there's no way to reuse state or suspense caches between the two renders.

[shuding]

There's react-dom/server.browser.js where you can use renderToString and renderToStaticMarkup in the server/browser environments, but renderToNodeStream is only available on the server. Does pipeToNodeWritable have the same restriction? Is it possible to have it working in a browser-like environment with an equivalent Node writable implementation?

[ad1992]

As mentioned in #104, the API pipeToNodeWritable been renamed to renderToPipeableStream, and onReadyToStream is now renamed to onCompleteShell so can we update this post to use the new API?

[gaearon]

Thanks, updated!