davila7--claude-code-templates/cli-tool/components/skills/web-development/react-best-practices/references/rules/async-suspense-boundaries.md

title, impact, impactDescription, tags

title	impact	impactDescription	tags
Strategic Suspense Boundaries	HIGH	faster initial paint	async, suspense, streaming, layout-shift

Strategic Suspense Boundaries

Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.

Incorrect (wrapper blocked by data fetching):

async function Page() {
  const data = await fetchData() // Blocks entire page
  
  return (
    <div>
      <div>Sidebar</div>
      <div>Header</div>
      <div>
        <DataDisplay data={data} />
      </div>
      <div>Footer</div>
    </div>
  )
}

The entire layout waits for data even though only the middle section needs it.

Correct (wrapper shows immediately, data streams in):

function Page() {
  return (
    <div>
      <div>Sidebar</div>
      <div>Header</div>
      <div>
        <Suspense fallback={<Skeleton />}>
          <DataDisplay />
        </Suspense>
      </div>
      <div>Footer</div>
    </div>
  )
}

async function DataDisplay() {
  const data = await fetchData() // Only blocks this component
  return <div>{data.content}</div>
}

Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.

When NOT to use this pattern:

• Critical data needed for layout decisions (affects positioning)
• SEO-critical content above the fold
• Small, fast queries where suspense overhead isn't worth it
• When you want to avoid layout shift (loading → content jump)

Trade-off: Faster initial paint vs potential layout shift. Choose based on your UX priorities.