docs: react 18, streaming SSR, rsc with new apis

[huozhi]

Documentation / Examples

Separate react 18 into 3 parts:

• Basic - bump react only
• Streaming SSR - streaming related
• Server Components - react server components specific

And and next/streaming as new API

• Make sure the linting passes by running yarn lint

[kachkaev]

Apologies for an unsolicited review 😅 I was mainly curious in this PR as a consumer of docs, but could not resist from leaving a couple of comments. Great stuff – thanks a lot for your work on React 18 support! 🚀

[huozhi]

@kachkaev Thanks for the nice feedback!

[kara]

Overall, these new docs look great! Very thoughtfully done :)

Below are mostly stylistic/grammatical nitpicks, though there are a few places where I think more clarification and examples would be useful for folks with less context than you.

[kara]

A few more comments (realized I missed the RSC file!)

[kara]

Thanks for making all the changes! A few more comments

[leerob]

We will need to reflect the changes made here, as well: #34068

[kara]

LGTM!

[devknoll]

Not strictly identical, as React.lazy doesn't do any preloading. Might be worth suggesting that you continue using next/dynamic for now for performance?

[huozhi]

When we enable { suspense: true } it's using React.lazy and doesn't do preloading I think?

[devknoll]

Oh, I see the issue -- we just haven't implemented the preloading yet (since it happens after the shell is flushed, where all of the existing preloading is done today), but we should. Otherwise there's no reason to have the { suspense: true } option instead of just recommending that people use React.lazy instead.

[gaearon]

The need for {suspense: true} makes it feel second-class. Do we plan to flip the default at some point in the future?

[devknoll]

The issue is that currently that would be a breaking change without an incremental upgrade path: your application using next/dynamic would break when upgrading to React 18 unless you add suspense boundaries first, but you can't add suspense boundaries until you upgrade to React 18. It also changes the semantics a bit, since pre-Suspense, the loading state is associated with the next/dynamic component, rather than the parent where the component is rendered.

Changing the default in the future is a possibility, but it's likely a major version away. Some shorter term options might be:

• If we could detect that we're rendering inside a <Suspense> boundary, we could assume you want the suspense behavior
• If we could somehow port the preloading behavior to React.lazy, we could push users toward that instead, when using React>=18

Both of these options would probably require some support in React though.

[devknoll]

It occurred to me that with facebook/react#23304 and facebook/react#23267 this might not actually be a breaking change anymore, if the transition semantics apply to root.render() as well... Would need to investigate further though.

[devknoll]

I think what we could theoretically do is use suspense by default during SSR and initial hydration if you're using React>=18, since that behavior shouldn't change (after the next RC).

For client-side navigations that would still be at risk of suspending, we could synchronously render the legacy non-Suspense based fallback that you provide with next/dynamic, and then also warn that you should add a suspense boundary and move your fallback there instead.

Let me think about it some more.

[devknoll]

Just noticed that facebook/react#23304 does in fact change the behavior for root.render(...) as long as it's not wrapped in flushSync. So yeah, it would probably make sense to make this change.

Thanks for flagging @gaearon

[devknoll]

I think it might be worth adding a caveat to the main React 18 doc about using any existing (i.e. pre-React 18) suspense libraries, especially if you're relying on a library like react-ssr-prepass. This might not apply to many Next.js users though, unsure.

[leerob]

Overall looks really great!

[leerob]

Wanted to make sure this is included in the next release, so merged - if there are any additional comments here unresolved or further questions, we can do a follow up 😄

Thank you!