Server Components and Suspense

It must return the identical promise for a given key on every render, dedupe requests already in flight, remember rejections as well as results, and be scoped per request on the server so data cannot leak between users.

Nothing can be flushed until the shell is renderable, and the shell is everything outside pending Suspense boundaries — including that top-level await. Boundaries below it are irrelevant. The fix is to move the slow work inside a boundary, or start the request early and pass the unawaited promise down to a suspended child.

Sibling boundaries reveal in completion order, not document order, so a later section can pop in first. Stable React 19 has no reveal-order coordinator, so you enforce order structurally: nest boundaries so an outer one must reveal before its children, or group the sections behind a single boundary that reveals them together.

Promises are serializable across the RSC boundary. React sends the prop as a pending reference and streams the resolved value as a later chunk of the same response, so the server does not block. The resolved value must itself be serializable, and rejection needs an error boundary.

The secret-bearing call and the heavy formatting belong in Server Components, because that code never ships to the browser. The modal toggle and the click-driven table sort need state and event handlers, so they must be Client Components.

The directive makes the barrel a client entry point, so every module it re-exports — and everything those import — becomes client code. The fix is to remove it from the barrel and mark only the individual modules that genuinely need interactivity.

localStorage does not exist on the server, so the server rendered a default theme while the browser's first render read the stored one — two different trees. Fix it by rendering a server-known default and applying the stored theme after hydration, or by setting it before hydration outside React's tree.

onRecoverableError is an option of hydrateRoot and createRoot that React calls when it hit an error and recovered by itself — typically a hydration error it fixed by re-rendering that content on the client. The UI is correct, so wire it to your error reporter.

If hydrateRoot has already started, React captures the click on the root container, prioritizes hydrating the subtree the user touched, and replays the event once that subtree is ready. If the bundle has not executed yet, no listener exists and the click is lost.

onShellReady fires when everything outside Suspense boundaries has rendered; piping there streams and locks the status code immediately. onAllReady fires only after every boundary has resolved; piping there gives up streaming but keeps the status changeable until the whole page is known good.

React defines only the render-time protocol: suspend on a pending promise, retry when it settles, surface rejection to an error boundary. Caching, deduping, invalidation, revalidation, retries and server-to-client data transfer are policy, and a framework or library supplies them.

Place a boundary where a placeholder can replace a region without moving anything around it, and where that region's data genuinely arrives at a different time from its neighbours. One boundary makes the whole page wait on its slowest part; a boundary per component produces a flickering mosaic that reflows repeatedly.

Treat the server-to-client prop boundary as a published API, not an internal call. Define an explicit view model per boundary, map to it in one auditable place per entity, and review it for three things: what the user can read, how many bytes it costs, and how stable the shape is.

Hydration cost scales with the size of the client component tree, not with what the user can see. Reduce it by keeping non-interactive parts out of that tree and splitting what remains so interactive regions hydrate first, then verify with real-user interaction data.

Before hydration the browser can still submit the form the ordinary HTML way, so the mutation happens provided the action resolves to a real server endpoint. Everything React layers on — pending UI, optimistic updates, staying on the page — requires hydration.

The RSC payload is a stream of serialized rows describing the rendered server tree. A suspended subtree is emitted as a placeholder reference immediately, with its resolved rows arriving later in the same stream. On a client navigation the browser fetches that payload instead of HTML, so boundaries still let part of the new screen render before the slow parts arrive.

Set a timer and call the abort function that renderToPipeableStream returns, or abort the AbortController whose signal you passed to renderToReadableStream. React stops server work, sends the unresolved boundaries' fallbacks, closes the stream, and the client renders those regions itself.