Skip to main content
rule CX Codex

async-suspense-boundaries — Claude Code rule: what it does

async-suspense-boundaries guides Claude Code to place data fetching behind Suspense boundaries so headers, sidebars, and layout shells render without blocking.

MIT ★ 7,191 updated 2026-10-24

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/async-suspense-boundaries.md
Open on GitHub

What async-suspense-boundaries does

The rule stops the agent from blocking an entire layout with top-level await calls in async components. Instead of forcing the parent view to pause, it isolates data queries in dedicated child components wrapped in Suspense. Outer layout elements like headers and navigation appear immediately.

The guidance outlines two implementations: moving await directly into child components, or initiating a fetch early and passing that raw promise to multiple consumers via the use hook. Passing a shared promise prevents duplicate network calls when adjacent widgets rely on the identical payload.

This pattern trades potential layout shift for earlier initial paint. The rule explicitly advises against Suspense when data dictates page positioning, belongs in above-the-fold content for search engines, or runs fast enough that boundary overhead hurts more than it helps.

What it helps with

  • render layout shells immediately while child data streams in
  • isolate blocking await statements inside nested UI components
  • pass an unresolved promise to sibling components via use()
  • prevent slow backend queries from halting header and navigation renders

Example prompts for the agent

  • Refactor Page.tsx so the shell renders immediately and data displays inside a Suspense boundary
  • Pass the unawaited fetch promise into child components and unwrap it with use
  • Review this async dashboard component to prevent layout blocking during queries

How to install async-suspense-boundaries

Manually: put the files in place

.claude/rules/async-suspense-boundaries.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about async-suspense-boundaries

How do I install async-suspense-boundaries in Claude Code?

Save the rule file to your project repository at .claude/rules/async-suspense-boundaries.md.

What does async-suspense-boundaries do?

It guides Claude Code to stream UI by wrapping asynchronous data components in Suspense boundaries rather than awaiting data before rendering page containers.

When should this Suspense pattern be avoided?

Skip it when data dictates layout geometry, feeds critical above-the-fold SEO text, or comes from tiny queries where boundary overhead outweighs streaming benefits.

Source text

async-suspense-boundaries.md · MIT
---
title: Strategic Suspense Boundaries
impact: HIGH
impactDescription: faster initial paint
tags: 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):**

```tsx
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):**

```tsx
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.

**Alternative (share promise across components):**

```tsx
function Page() {
  // Start fetch immediately, but don't await
  const dataPromise = fetchData()
  
  return (
    <div>
      <div>Sidebar</div>
      <div>Header</div>
      <Suspense fallback={<Skeleton />}>
        <DataDisplay dataPromise={dataPromise} />
        <DataSummary dataPromise={dataPromise} />
      </Suspense>
      <div>Footer</div>
    </div>
  )
}

function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
  const data = use(dataPromise) // Unwraps the promise
  return <div>{data.content}</div>
}

function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
  const data = use(dataPromise) // Reuses the same promise
  return <div>{data.summary}</div>
}
```

Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.

**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.

© tech-leads-club · MIT · tech-leads-club/agent-skills

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set130

The whole set →
architecture-avoid-boolean-props The architecture-avoid-boolean-props rule keeps component variants out of boolean props and moves them into composition. Use it when conditional UI branches start spreading across a component. CX Codex +1 ★ 7,191repo stars rendering-hydration-no-flicker rendering-hydration-no-flicker prevents server render failures and interface flickering when displaying content tied to browser storage. CX Codex +1 ★ 7,191repo stars bundle-barrel-imports The bundle-barrel-imports rule steers imports away from barrel files and toward source modules. It helps when a package exposes many re-exports and slows loading. CX Codex +1 ★ 7,191repo stars patterns-explicit-variants patterns-explicit-variants — a rule that pushes one component per mode instead of a single component buried under boolean props. The call site then says what renders. CX Codex +1 ★ 7,191repo stars architecture-compound-components The architecture-compound-components rule describes splitting complex UI components into pieces that share state through context. It fits components that have accumulated render props and conditional options. CX Codex +1 ★ 7,191repo stars state-decouple-implementation state-decouple-implementation — a Claude Code rule that keeps state management inside providers and exposes only a context interface to UI components. Swap useState for Zustand or a server sync without touching a single UI file. CX Codex +1 ★ 7,191repo stars rerender-functional-setstate The rerender-functional-setstate rule recommends functional state updates when the next React value depends on the current one. It helps callbacks avoid stale state and unnecessary dependencies. CX Codex +1 ★ 7,191repo stars state-lift-state state-lift-state — a Claude Code rule that moves React state into a provider component, so siblings outside the main UI read and update it without prop drilling or refs. CX Codex +1 ★ 7,191repo stars

Project sponsors

Companies that keep this analytics open