Unverified Commit 7356b0bc authored by Joseph's avatar Joseph Committed by GitHub

docs: note Suspense requirement for connection() with Cache Components (#100810)

## Summary

The `connection()` API reference did not say that, with Cache
Components, the calling component needs a `<Suspense>` boundary above
it. The caching guide and the `blocking-prerender-dynamic` error page
both require one, and the `io()` and `navigation()` references show it.

Adds a Good to know bullet: the boundary can be direct or an ancestor
such as `loading.js`, the nearest fallback is prerendered into the
static shell, and without a boundary navigations block instead of being
instant.

## Verification

- Checked link targets: `loading`, glossary `#static-shell`,
`/docs/messages/blocking-prerender-dynamic`

<!-- NEXT_JS_LLM -->
parent c41d1beb
...@@ -81,6 +81,7 @@ function connection(): Promise<void> ...@@ -81,6 +81,7 @@ function connection(): Promise<void>
- `connection` replaces [`unstable_noStore`](/docs/app/api-reference/functions/unstable_noStore) to better align with the future of Next.js. - `connection` replaces [`unstable_noStore`](/docs/app/api-reference/functions/unstable_noStore) to better align with the future of Next.js.
- The function is only necessary when dynamic rendering is required and common Request-time APIs are not used. - The function is only necessary when dynamic rendering is required and common Request-time APIs are not used.
- With [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents), place the component that calls `connection()` inside a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary, either directly or through an ancestor such as a [`loading.js`](/docs/app/api-reference/file-conventions/loading) file. The nearest boundary's fallback is prerendered into the [static shell](/docs/app/glossary#static-shell), and the code after `connection()` runs at request time. Without a boundary, navigations to the route [block instead of being instant](/docs/messages/blocking-prerender-dynamic).
- With [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents), prefer [`io()`](/docs/app/api-reference/functions/io) for excluding content from the static shell. It works the same way but can also be cached and prefetched. Reach for `connection()` only when rendering should wait for a real user request. - With [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents), prefer [`io()`](/docs/app/api-reference/functions/io) for excluding content from the static shell. It works the same way but can also be cached and prefetched. Reach for `connection()` only when rendering should wait for a real user request.
### Version History ### Version History
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment