LLM Best Practices

Suspense boundary

2 min read

View markdown source

Overview

This page is the atomic definition. React streaming and async patterns live at react and nextjs.

Definition

A Suspense boundary is a <Suspense fallback={<Spinner />}> wrapper that catches “not ready” signals from its child subtree. When a child component throws a Promise (the mechanism React uses for lazy-loaded code and data), the nearest ancestor Suspense boundary catches the throw, renders the fallback prop instead, and resumes rendering the child when the Promise resolves. This enables streaming HTML: Next.js App Router can flush the HTML shell to the browser immediately and stream each Suspense-bounded section as its data resolves, reducing Time to First Byte and improving perceived load speed. Nesting boundaries gives fine-grained control: a spinner per card rather than one full-page spinner. Error boundaries (a separate construct) catch synchronous throws; Suspense boundaries catch async throws.

When it applies

Wrap every React.lazy() import with a Suspense boundary. In Next.js App Router, Suspense boundaries define streaming units, so place them around sections that depend on slow data sources. Avoid a single root boundary that blocks the entire page.

Example

import { Suspense, lazy } from "react"
const HeavyChart = lazy(() => import("./HeavyChart"))
 
function Dashboard() {
  return (
    <div>
      <Header />
      <Suspense fallback={<ChartSkeleton />}>
        <HeavyChart />
      </Suspense>
    </div>
  )
}
  • react - the full React rendering model including concurrent features.
  • nextjs - Next.js App Router uses Suspense for streaming SSR.
  • code-splitting - React.lazy requires a Suspense boundary.
  • hydration - each Suspense-bounded island hydrates independently.
  • server-component - Server Components and Suspense compose to enable streaming.

Citing this term

See Suspense boundary (llmbestpractices.com/glossary/suspense-boundary).

Graph View

Backlinks