[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 list 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
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.