docs: Clarify Suspense misconceptions in documentation

[kostyniuk]

What?

Add clarification on Suspense misconceptions and its behavior regarding request-time rendering.

Why?

Developers frequently assume makes components “dynamic,” leading to unintended runtime work or confusion.

How?

Add a “Suspense misconceptions” callout to the Cache Components doc.

[ijjk]

Allow CI Workflow Run

• approve CI run for commit: 33ae415

Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer

[ijjk]

Allow CI Workflow Run

• approve CI run for commit: 33ae415

Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer

[vercel]

Suggested change

	A common misconception is that `<Suspense>` triggers request-time rendering. This is not the case:
	- **Suspense does not defer rendering to request time.** Its role is to define a boundary for fallback UI while async content is being prepared or streamed.
	- Components inside `<Suspense>` can still execute at build/prerender time if they have no runtime dependencies.
	- Only Dynamic APIs or [`connection()`](/docs/app/api-reference/functions/connection) force request-time execution.
	A common misconception is that `<Suspense>` automatically triggers request-time rendering. This is not the case:
	- **Suspense alone does not force request-time rendering.** While Suspense defines a boundary for fallback UI, the actual deferral to request time only happens when components access Dynamic APIs or [`connection()`](/docs/app/api-reference/functions/connection). Components inside `<Suspense>` can still execute at build/prerender time if they have no runtime dependencies.
	- Only Dynamic APIs or [`connection()`](/docs/app/api-reference/functions/connection) actually trigger request-time execution. Wrapping a component in `<Suspense>` without these dependencies doesn't defer its rendering.

The new section contradicts earlier documentation that explicitly states Suspense is used to "defer rendering to request time." The wording should be clarified to distinguish between Suspense being a mechanism for deferred rendering versus being a trigger for it.

View Details

Analysis

Documentation contradiction: Suspense and deferred rendering

What fails: Section "Suspense misconception" contradicts earlier documentation about Suspense and request-time rendering.

How to reproduce: Read the document:

• Line 36: "Defer rendering to request time by wrapping components in React's <Suspense>"
• Line 91: "To defer rendering to request time, a parent component must provide fallback UI using a Suspense boundary"
• Line 250: "Suspense does not defer rendering to request time"

Result: The statement at line 250 directly contradicts the usage pattern documented in lines 36 and 91.

Expected: The documentation should clarify that Suspense is the mechanism for deferring rendering (you wrap components in Suspense to defer them), but Suspense alone doesn't automatically trigger request-time rendering without runtime dependencies (Dynamic APIs, connection(), etc.).

Fix: Changed line 250 from "Suspense does not defer rendering to request time" to "Suspense alone does not force request-time rendering" and clarified that the actual trigger is Dynamic APIs or connection(), not Suspense itself. This preserves the misconception clarification while maintaining consistency with earlier documentation.