From af59d7e17c3567f2586432969b885b14de156107 Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Wed, 8 Jul 2026 16:02:00 +0200 Subject: [PATCH 1/3] Clarify use vs await --- src/content/reference/react/use.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md index 1780f82e7b5..fe31f361422 100644 --- a/src/content/reference/react/use.md +++ b/src/content/reference/react/use.md @@ -1131,7 +1131,7 @@ A Server Component can also start a Promise without awaiting it and pass the Pro ```js // Server Component export default function App() { - // Not awaited: starts here, resolves on the client. + // Not awaited: starts on the server, streamed to the client. const messagePromise = fetchMessage(); return ; } @@ -1149,9 +1149,9 @@ export function Message({ messagePromise }) { } ``` -Prefer `await` in a Server Component when possible, since it keeps the data fetching on the server. 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`. +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`. -You can also pass promise as a prop to a Client Component without awaiting it, and then read it with `use(promise)` to suspend deeper in the tree. This allows more of the surrounding UI to complete while the Promise is pending. A common case is interactive content like popovers and tooltips, where the data is needed only after a hover or click. Client Components can't `await`, so they rely on `use` to suspend on a Promise. +Pass a Promise to a Client Component to suspend deeper in the tree, letting more of the surrounding UI render while the Promise is pending. A common case is interactive content like popovers and tooltips, where the data is only needed after a hover or click. Client Components can't `await`, so they read a Promise with `use`. In either case, wrap the component that reads the Promise in a Suspense boundary so React can show a fallback while the Promise is pending. See [Revealing content together at once](/reference/react/Suspense#revealing-content-together-at-once) for guidance on boundary placement. From a3c5c704aead18bdbe54d2c417ac08120865a09e Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Wed, 8 Jul 2026 18:42:35 +0200 Subject: [PATCH 2/3] Refine based on feedback --- src/content/reference/react/use.md | 33 ++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md index fe31f361422..9490bd9eada 100644 --- a/src/content/reference/react/use.md +++ b/src/content/reference/react/use.md @@ -1113,47 +1113,58 @@ root.render( #### Should I resolve a Promise in a Server or Client Component? {/*resolve-promise-in-server-or-client-component*/} -A Promise can be resolved with `await` in a Server Component, or passed as a prop to a Client Component and resolved there with `use`. +If you have a Promise, at some point you need to unwrap it to read its value. You unwrap it with `await` on the server, and with `use` on the client. -Using `await` in a Server Component suspends the Server Component itself, and the Client Component receives the resolved value as a prop: +Usually, the simplest option is to `await` the Promise where you create it. The Server Component suspends until the data is ready, and everything below it waits too: ```js // Server Component export default async function App() { - // Will suspend the Server Component. const messageContent = await fetchMessage(); return ; } ``` -A Server Component can also start a Promise without awaiting it and pass the Promise to a Client Component. The Server Component returns immediately, and the Client Component suspends when it calls `use`: +However, you don't have to unwrap it right away. You can pass the Promise down as a prop, and unwrap it deeper in the tree. The component that reads the Promise still suspends, but only that part of the tree waits for the data. Wrap that component in a [``](/reference/react/Suspense) boundary to show a fallback while the rest of the page renders immediately. + +For example, a deeper Server Component can `await` the Promise it receives: ```js +import { Suspense } from 'react'; + // Server Component export default function App() { - // Not awaited: starts on the server, streamed to the client. const messagePromise = fetchMessage(); - return ; + return ( + ⌛Downloading message...

}> + + + ); +} + +// Server Component +async function Message({ messagePromise }) { + const messageContent = await messagePromise; + return

{messageContent}

; } ``` +Or, in a separate file, a Client Component can unwrap the same Promise with `use`: + ```js // Client Component 'use client'; import { use } from 'react'; export function Message({ messagePromise }) { - // Will suspend until the data is available. const messageContent = use(messagePromise); return

{messageContent}

; } ``` -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`. - -Pass a Promise to a Client Component to suspend deeper in the tree, letting more of the surrounding UI render while the Promise is pending. A common case is interactive content like popovers and tooltips, where the data is only needed after a hover or click. Client Components can't `await`, so they read a Promise with `use`. +Passing the Promise down works the same way in both cases. Both suspend where the Promise is read, and both unblock the UI above. The only difference is that Client Components can't `await` during render, so they unwrap the Promise with `use` instead. A common case is interactive content like popovers and tooltips, where the data is only needed after a hover or click. -In either case, wrap the component that reads the Promise in a Suspense boundary so React can show a fallback while the Promise is pending. See [Revealing content together at once](/reference/react/Suspense#revealing-content-together-at-once) for guidance on boundary placement. +See [Revealing content together at once](/reference/react/Suspense#revealing-content-together-at-once) for guidance on where to place Suspense boundaries. From b72f656ce46799709b065a7f85095628a873e9dd Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Wed, 8 Jul 2026 18:56:38 +0200 Subject: [PATCH 3/3] Address review comments --- src/content/reference/react/use.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md index 9490bd9eada..6e2d490ee93 100644 --- a/src/content/reference/react/use.md +++ b/src/content/reference/react/use.md @@ -1113,7 +1113,7 @@ root.render( #### Should I resolve a Promise in a Server or Client Component? {/*resolve-promise-in-server-or-client-component*/} -If you have a Promise, at some point you need to unwrap it to read its value. You unwrap it with `await` on the server, and with `use` on the client. +If you have a Promise, at some point you need to unwrap it to read its value. You unwrap it with `await` in a Server Component, and with `use` in a Client Component. Usually, the simplest option is to `await` the Promise where you create it. The Server Component suspends until the data is ready, and everything below it waits too: @@ -1154,6 +1154,7 @@ Or, in a separate file, a Client Component can unwrap the same Promise with `use ```js // Client Component 'use client'; + import { use } from 'react'; export function Message({ messagePromise }) {