[Suspense] Document what activates a boundary and define Suspense-enabled frameworks#8505
[Suspense] Document what activates a boundary and define Suspense-enabled frameworks#8505aurorascharff wants to merge 4 commits into
Conversation
aurorascharff
changed the title
Size changesDetails📦 Next.js Bundle Analysis for react-devThis analysis was generated by the Next.js Bundle Analysis action. 🤖 This PR introduced no changes to the JavaScript bundle! 🙌 |
There was a problem hiding this comment.
Pull request overview
Updates the <Suspense> reference to replace an outdated note with a new, linkable section that enumerates the different kinds of work/resources that can activate a Suspense boundary, while keeping data-fetching caveats in a <Note>.
Changes:
- Adds a new “What activates a Suspense boundary” subsection with a broader activation list (e.g.,
lazy,use, stylesheets, fonts, images, SSR streaming, experimentaldefer). - Moves data-fetching caveats into a
<Note>and tweaks wording around framework support (“built-in Suspense support”). - Removes Next.js from the earlier “Suspense-enabled frameworks” mention in favor of describing Server Components /
use()behavior.
Docs review checklist (by guide)
docs-writer-reference
-
src/content/reference/react/Suspense.md:217Bullet uses<img onLoad>-style wording that reads like JSX but isn’t valid JSX and is a bit unclear/contradictory in context.
docs-voice
-
src/content/reference/react/Suspense.md:217Consider rephrasing to use inline code for the prop name (onLoad) and clarify the “not enabled by default” vs “opts out” wording.
docs-components
- No issues found in the changed region (callout spacing and section divider usage look consistent).
docs-sandpack
- No issues found related to Sandpack formatting/content in the changed region.
Please create a plan to address the unchecked checklist item(s).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| <Note> | ||
| --- | ||
|
|
||
| ### What activates a Suspense boundary {/*what-activates-a-suspense-boundary*/} |
There was a problem hiding this comment.
Very excited to see these being called out and updated!
My understanding is that a "suspense enabled framework" is a framework that wraps these features that activates a suspense boundaries . If that is true could we specifically call it out what suspense enabled means?
| The exact way you would load data in the `Albums` component above depends on your framework. If you use a Suspense-enabled framework, you'll find the details in its data fetching documentation. | ||
| The exact way you would load data in the `Albums` component above depends on your framework. If you use a framework with built-in Suspense support, you'll find the details in its data fetching documentation. | ||
|
|
||
| Suspense-enabled data fetching without the use of an opinionated framework is not yet supported. The requirements for implementing a Suspense-enabled data source are unstable and undocumented. An official API for integrating data sources with Suspense will be released in a future version of React. |
There was a problem hiding this comment.
This line is out of date because of yours and @rickhanlonii great work on the use() docs.
There was a problem hiding this comment.
Nice catch!!! Updating!
aurorascharff
changed the title
| - If Suspense was displaying content for the tree, but then it suspended again, the `fallback` will be shown again unless the update causing it was caused by [`startTransition`](/reference/react/startTransition) or [`useDeferredValue`](/reference/react/useDeferredValue). | ||
| - If React needs to hide the already visible content because it suspended again, it will clean up [layout Effects](/reference/react/useLayoutEffect) in the content tree. When the content is ready to be shown again, React will fire the layout Effects again. This ensures that Effects measuring the DOM layout don't try to do this while the content is hidden. | ||
| - React includes under-the-hood optimizations like *Streaming Server Rendering* and *Selective Hydration* that are integrated with Suspense. Read [an architectural overview](https://github.com/reactwg/react-18/discussions/37) and watch [a technical talk](https://www.youtube.com/watch?v=pj5N-Khihgc) to learn more. | ||
|
|
There was a problem hiding this comment.
I opened issue #8490 about the need for a caveat regarding React's batching of Suspense content, which has resulted in several issues in the React repo that can be solved with documentation. If we can add it to this pr, it would be great. I am thinking something like this:
| - React waits at least ~300ms before revealing a `Suspense` fallback, and applies the same throttle across different boundaries. This reduces flicker when nested boundaries resolve in quick succession, which is common during [streaming server rendering](/reference/react-dom/server). Content that becomes ready within that window is held and revealed together once the window closes. A boundary that resolves before its fallback is committed—for example, synchronously, or within roughly 10ms—may skip the fallback entirely. | |
| ### What activates a Suspense boundary {/*what-activates-a-suspense-boundary*/} | ||
|
|
||
| **Only Suspense-enabled data sources will activate the Suspense component.** They include: | ||
| A Suspense boundary displays its `fallback` while its content is loading, and it can also wait on other resources before revealing that content. The following activate a boundary: |
There was a problem hiding this comment.
"activate a boundary" is a bit ambiguous. We shouldn't necessarily say "shows a fallback" because that depends on the kind of update (Transition, sync etc.).
Wdyt about "The following block content from being revealed"?
| - Reading a Promise with [`use`](/reference/react/use), including data streamed from [Server Components](/reference/rsc/server-components) and integrations from frameworks like [Relay](https://relay.dev/docs/guided-tour/rendering/loading-states/). | ||
| - Loading a stylesheet rendered with [`<link rel="stylesheet">` and a `precedence` prop.](/reference/react-dom/components/link#special-rendering-behavior) React blocks the boundary until the stylesheet loads, up to a timeout. | ||
| - Loading fonts. React blocks a streamed boundary until [`document.fonts.ready`](https://developer.mozilla.org/en-US/docs/Web/API/FontFaceSet/ready) resolves, up to a timeout. Fonts also block a [`<ViewTransition>`](/reference/react/ViewTransition) update. | ||
| - Streaming a large boundary's HTML during server rendering. React reveals the content as the HTML arrives. |
There was a problem hiding this comment.
The other examples are probably self-explanatory. This one could do with an example. Examples for all would be nice with a side-by-side with a Suspense implementation that wouldn't block (e.g. with just some simple DOM operations).
| #### What is a Suspense-enabled framework? {/*what-is-a-suspense-enabled-framework*/} | ||
|
|
||
| The exact way you would load data in the `Albums` component above depends on your framework. If you use a Suspense-enabled framework, you'll find the details in its data fetching documentation. | ||
| A *Suspense-enabled framework* integrates data fetching with Suspense, so that reading data in a component activates the nearest boundary. The exact way you load data in the `Albums` component above depends on your framework, and you'll find the details in its data fetching documentation. |
There was a problem hiding this comment.
Is this still needed? Frameworks would just use as well. This section usually gets people asking how they could become a "Suspense-enabled framework" which is just use.
Why: The Suspense reference said only Suspense-enabled data sources activate a boundary. That's outdated — many things activate Suspense now — and the term "Suspense-enabled framework" was used across several pages without ever being defined. The note also claimed framework-less data fetching was unsupported and undocumented, which the recent
use()docs have since made untrue.What: Replaces that note with a linkable section covering what actually activates a boundary, adds a definition of "Suspense-enabled framework," and points framework-less fetching at
use()with a cached Promise. Also drops Next.js from the "Suspense-enabled frameworks" line, since it relies on Server Components anduse()rather than a custom integration.The behavior and framing were verified by the React team.