[use] Rework await vs use DeepDive to fix inaccurate framing

[aurorascharff]

Summary

Rewrites the "Should I resolve a Promise in a Server or Client Component?" DeepDive on the use reference page.

The previous text said to prefer await in a Server Component "since it keeps the data fetching on the server". That's not accurate: when the Promise is created in a Server Component, the fetch runs on the server whether you await it or pass it down, passing an unawaited Promise streams the resolved value to the client, it doesn't move the fetch (raised by @samselikoff). The section also taught passing a Promise down as something specific to use, when the same technique works with await in a deeper Server Component.

New framing (from discussion with @gaearon)

• await unwraps a Promise on the server, use unwraps it on the client.
• Unwrapping where you create the Promise is usually simplest, but blocks everything below.
• Passing the Promise down and unwrapping it deeper is a general technique to unblock the surrounding UI, not a use feature. Wrapped in <Suspense>, only that part of the tree waits.
• Three examples: blocking await, pass down + await deeper (unblocking on the server), pass down + use deeper (unblocking on the client).
• The closing teaches the only real rule: Client Components can't await during render, so they unwrap with use. The popover/tooltip case stays attached to the client example.

[github-actions]

Size changes

Details

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

[gaearon]

Prefer await in a Server Component when possible. If a Server Component above already awaits the data, pass the resolved value down as a prop instead of creating a new Promise to call use.

This still feels a bit too strong to me. It sounds as if use is strictly worse but it's not. It's just that if you need the actual Promise on the server, you await where you need it, and if you need it on the client, you use that Promise instead.

[Copilot]

Pull request overview

This PR rewrites the “Should I resolve a Promise in a Server or Client Component?” DeepDive on the use reference page to clarify that await unwraps Promises in Server Components while use unwraps Promises in Client Components, and to frame “passing a Promise down” as a general Suspense technique rather than something specific to use.

Changes:

• Reframes the DeepDive to focus on where the Promise is unwrapped (server via await, client via use).
• Adds an example showing passing a Promise down and awaiting it deeper within a <Suspense> boundary.
• Updates the closing guidance to emphasize the real constraint: Client Components can’t await during render.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.