[Umbrella] Releasing Suspense

[acdlite]

Let's use this issue to track the remaining tasks for releasing Suspense to open source.

Last updated: March 24, 2022

Blog post: The Plan for React 18

Completed: React 16

• [x] Release <Suspense> with React.lazy for client-side lazy loading

Completed: React 18 Alpha

• [x] Implement concurrent rendering, which is a prerequisite to everything else.
• [x] Fix fundamental flaws in the concurrency model that made the behavior difficult to understand and caused many bugs.
• [x] Rewrite how React traverses the tree to unblock fixing Suspense quirks.
• [x] Redesign how React integrates with the scheduler to simplify the model, fix bugs, and prepare for native browser scheduling.
• [x] Fix <Suspense> quirks: Previously, effects would fire inside a suspended tree too early. For example, you would see an effect from a component that's still hidden behind a placeholder. Now effects will run only after the content has been revealed. We expect this to fix existing application code bugs.
• [x] Hiding and showing existing content should re-fire layout effects: If a component that's already visible suspends, we show a placeholder, and later show it again. However, there was no way for the component to know that it was hidden or shown. For example, a tooltip component measuring its screen position would get incorrect measurements while it's hidden. Now we fire useLayoutEffect cleanup (same as componentWillUnmount) on "hide", and useLayoutEffect setup (same as componentDidMount) on "show". We expect this to fix existing application and library code bugs.
• [x] <Suspense> on the server no longer throws: It used to be a hard error to render <Suspense> in a tree on the server. Now, for the old server renderer, it silently emits the fallback (and lets the client try to render the content instead). This shouldn't affect existing apps because previously it was not possible to render <Suspense> on the server at all.
• [x] startTransition lets you avoid hiding existing content even if it suspends again. This is useful to implement the "show old data while refetching" pattern with minimal code.
• [x] Built-in throttling of Suspense reveals: To avoid updating the screen too often and causing visual jank, React "waits" a little bit before revealing the next level of spinners — in case even more content is available by that time. In other words, revealing nested Suspense fallbacks is automatically throttled by React.
• [x] New Streaming Suspense Server Renderer:
  • [x] Initial streaming renderer implementation.
  • [x] React.lazy works with SSR out of the box.
  • [x] Streaming HTML: React uses your <Suspense> boundaries to stream the page HTML in visual chunks.
  • [x] Selective Hydration: React uses your <Suspense> boundaries to hydrate the page in chunks, improving responsiveness.
    • [x] React prioritizes hydrating the part of the page you are interacting with.
    • [x] React keeps the browser responsive during hydration of <Suspense> boundaries.
    • [x] React captures and replays missed events after hydration.
• [x] Technical preview of Server Components:
  • [x] Implement the server with support for suspending.
  • [x] Prototype a caching layer.
  • [x] Prototype React I/O libraries like react-fetch and react-pg.
  • [x] Support lazy-loaded elements for server trees.

Completed: React 18

• [x] Finalize New Streaming Suspense Server Renderer:
  • [x] Make it pass all of our existing tests.
  • [x] Prove it out in production (currently we use a hack in its place).
  • [x] Add the missing "static markup" APIs for things like emails.
  • [x] Fix known bugs with hydrating Suspense.
  • [x] Move the new server renderer from react-dom/unstable-fizz to react-dom/server.
• [x] Fall back to client rendering from closest <Suspense> on mismatches instead of patching up the tree.
• [x] Add onRecoverableError to gather production reports about SSR mismatches.

Features that may or may not appear in 18.x

• [ ] <SuspenseList> lets you declaratively coordinate the order in which <Suspense> nodes inside will reveal.
  • [x] Implementation.
  • [ ] Server support
  • [ ] Finalize and document the API.
• [ ] "Backup" <Suspense> boundaries (not final naming): A way to specify that you'd like React to ignore this boundary during initial render (as if it's not there), unless React is forced to hide existing content. We sometimes call these "ugly spinners" or "last resort spinners". This use case might seem a bit exotic but we've needed it quite a few times.
  • [x] Initial implementation as unstable_avoidThisFallback
  • [x] Server support
  • [ ] Pick a good name
• [ ] <Suspense> for CPU-bound trees (not final naming): A way to tell React to immediately show a placeholder without even trying to render the content. This is useful if you have an expensive tree inside. This use case is unrelated to network — it's about showing a spinner for some tree that takes a while to render. See https://github.com/facebook/react/pull/19936.
  • [x] Initial implementation as unstable_expectedLoadTime
  • [ ] Adjust the heuristics
  • [x] Server support
  • [ ] Pick a good name
• [ ] An API to prioritize hydrating a particular DOM element's parent tree.
  • [x] Implement as ReactDOM. unstable_scheduleHydration
  • [ ] Pick a name
• [ ] Reducing jank: Take another look at adjusting the small details to reduce any visual jank to the minimum. For example, throttle reveal of Suspense boundaries between siblings as well.

React 18.x (post-18.0): Suspense for Data Fetching

All of the above changes are foundational architectural improvements to <Suspense>. They fill the gaps in the mechanism and make it deeply integrated with all parts of React (client and server). However, they don't prescribe a particular data fetching strategy. That will likely come after the 18.0 release, and we're hoping that to have something during the next 18.x minor releases.

This work will include:

• [ ] React I/O libraries like react-fetch, which is a lightweight and easiest way to fetch data with Suspense.
  • [x] Initial implementation
  • [ ] Finalize the API
• [ ] Built-in Suspense <Cache> which will likely be the primary recommended way for third-party data fetching libraries to integrate with Suspense. (For example, react-fetch uses it internally.)
  • [x] Initial implementation
  • [ ] Try it in production
  • [ ] Investigate what's missing
  • [ ] Figure out the recommended strategy for normalized caches
• [x] Server Components, which will be the recommended way to fetch data with Suspense in a way that scales great and integrates with React Fetch as well as third-party libraries.
  • [x] Initial implementation
  • [x] Basic Server Context implementation
  • [x] Server Context features for refetching
  • [x] Figure out the layering between Server Components and New SSR
  • [ ] (This section has many follow-up questions, so it's incomplete)
• [ ] Clear documentation and recommendations for data fetching library authors on how to integrate with Suspense

[gaearon]

Btw, @rickhanlonii updated the time slicing demo (from the original JSConf Iceland talk) if you wanna play with it :-) as you can see some APIs have changed but they should make a bit more sense now (figuring out the right APIs and heuristics was a large part of the effort).

https://github.com/facebook/react/pull/21401 https://react-beta-seven.vercel.app/

(keep in mind the demo is not representative of the most efficient way to draw a chart per se, but shows some of the benefits we want to unlock in general for arbitrary component trees)

[gaearon]

Finalize other API semantics and defaults. (not started)

That’s one of the remaining areas to polish.

This is in progress. We've tweaked and unprefixed some APIs (for the experimental channel only). https://github.com/facebook/react/pull/21488

[ntucker]

@gaearon That's awesome! Does that mean a stable release with these things is coming soon? Will this be React 17.1?

[gaearon]

We are getting closer to the first release that would have an actual number version on it. It will be tagged as an alpha. Like always, we’ll announce it on the blog. A stable release is going to take place at least several months after that since we’re going to work closely with the ecosystem and it will take some more time to fill in the gaps. Sorry this is brief, preparing the communication for this is another part of the team’s ongoing work.

[zhangchao828]

With regard to:

Ecosystem compatibility and good defaults. It doesn't help if we release something that nobody can use today because it doesn't work with their libraries or existing approaches.

Is there anything the community can do to help?

At the company I work at, we're heavy users of MobX, and so we would be keen to help figure out how Concurrent Mode \ Time slicing can work with MobX. I imagine there are similar companies out there as well.

see: https://github.com/mobxjs/mobx-react-lite/issues/53#issuecomment-487371481

[gaearon]

Yesterday, we published The Plan for React 18.

tldr:

• We’ve started work on the React 18 release, which will be our next major version.
• We’ve created a Working Group to prepare the community for gradual adoption of new features in React 18.
• We’ve published a React 18 Alpha so that library authors can try it and provide feedback.

React 18 will include a lot of foundational work for Suspense. This includes a brand new streaming server renderer which uses the <Suspense> boundaries to stream HTML and to hydrate the page in chunks, dramatically improving responsiveness. However, Suspense for Data Fetching will likely not be a part of the first 18.0 release, but follow after (likely in a 18.x minor release).

To reflect the current roadmap, I have updated the initial post in this thread. It shows the work we have already done over these years (most checkboxes correspond to multiple months of work), and the remaining work is grouped by the release timeline.

[gaearon]

Additionally, I'd like to share this thread from @rickhanlonii reflecting on the journey to React 18 alpha. I hope it provides some insight on why these things are taking time and we could not get this Alpha out earlier.

[Jack-Works]

Hi! I'm trying to upgrade from the nightly version to alpha but I found unstable_getCacheForType wasn't included in the alpha version

[gaearon]

Yes, the Cache API is still more experimental than the rest so you’ll need an @experimental release to use that.

[koba04]

I know that removing componentWillMount, componentWillReceiveProps, and componentWillUpdate was postponed at the v17. Will these APIs be still kept in v18, or be only kept UNSAFE_ prefixed lifecycle methods like the migration plan? https://reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path

[gaearon]

We have not made a decision on this yet. We will include information about any deprecations or removals in future blog posts.

[Ayc0]

What would happen if a library uses the new APIs like startTransition but its users still uses ReactDOM.render instead of the new ReactDOM.createRoot? Will it crash?

[gaearon]

It won’t crash but it also won’t get treated as a transition. Just a regular state update.

[gaearon]

Wrote some updates on what we're working on and the state of different pieces. It's about React 18 overall but some parts there relate to Suspense: https://github.com/reactwg/react-18/discussions/98#discussioncomment-1318753

[gaearon]

I've updated the umbrella to document the current progress. There is nothing more blocking the initial React 18 release, so we've released the last call for feedback:

• https://github.com/reactjs/rfcs/pull/212
• https://github.com/reactjs/rfcs/pull/213

[gaearon]

We've been making some changes to the strategy, in particular, to avoid the need for "forked" IO libraries like react-fetch for every single use case. A wrapper could still make some things more ergonomic, but the current plan is to allow easy compatibility with any async/await code. This experimental API is the first step towards that: https://github.com/facebook/react/pull/25084

[tobias-tengler]

@gaearon is this new API superseding the Suspense cache (unstable_Cache) or are they meant to both exist alongside each other?

[gaearon]

I think we’re not super clear yet on whether Cache will be moving forward or not, but this API could potentially work together with it in the future.

[dante01yoon]

This might be outdated question after v18 release, but I wonder we don't need using loadable-components library for using Suspense in SSR?