docs: expand io reference#95147
Merged
Merged
Conversation
Adds when-to-use scenarios with a Client Component example, when-not-to carve-outs, an explicit connection() comparison, and updates the failure-mode description to match Cache Components' actual behavior.
Contributor
Stats skippedCommit: 11ac737 |
Contributor
Tests PassedCommit: 11ac737 |
aurorascharff
approved these changes
Jun 25, 2026
aurorascharff
left a comment
aurorascharff
left a comment
Contributor
There was a problem hiding this comment.
approved with comments
Contributor
There was a problem hiding this comment.
Pull request overview
Expands and reframes the io() API reference and related prerender error docs to clarify that, with Cache Components enabled, await io() (or use(io()) in Client Components) is the mechanism to keep subsequent synchronous dynamic reads out of the static shell, and to better differentiate io() from connection() in terms of prefetch behavior and composability.
Changes:
- Updates multiple “blocking prerender” error guides to recommend
io()as an alternative toconnection()with emphasis on static-shell exclusion and prefetch friendliness. - Adds “Suspend with
use(io())” guidance to Client Component error pages for truly per-visit synchronous reads that can’t be deferred to effects/events. - Rewrites the
io()reference page with clearer Server/Client usage examples, a “When you don’t needio()” section, and an updatedconnection()comparison + version history.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| errors/blocking-prerender-random.mdx | Reframes io() as the static-shell escape hatch and contrasts prefetch impact vs connection(). |
| errors/blocking-prerender-random-client.mdx | Adds a use(io()) Suspense pattern for Client Components that must compute per-visit values during SSR. |
| errors/blocking-prerender-current-time.mdx | Updates the io() alternative explanation consistent with the new framing. |
| errors/blocking-prerender-current-time-client.mdx | Adds a use(io()) Suspense option under “Other options” for per-visit “now” reads. |
| errors/blocking-prerender-crypto.mdx | Updates the io() alternative explanation consistent with the new framing. |
| errors/blocking-prerender-crypto-client.mdx | Adds a use(io()) Suspense pattern for Client Components using crypto.randomUUID() per visit. |
| docs/01-app/03-api-reference/04-functions/io.mdx | Major rewrite of io() reference: static-shell explanation, Server/Client examples, “don’t need io” section, updated connection() comparison, and version history. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
aurorascharff
approved these changes
Jun 25, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rewrites the
io()API reference around what it expresses: with Cache Componentsawait io()keeps the operation that follow afterward out of the static shell.Adds Server/Client usage examples and a composition note, a "When you don't need
io()" section, and reframes theconnection()comparison around prefetching.