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
.claude/rules/async-suspense-boundaries.mdWhat 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
awaitstatements 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.tsxso 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.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/async-suspense-boundaries.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/async-suspense-boundaries.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/async-suspense-boundaries.mdManually: put the files in place
.clinerules/async-suspense-boundaries.mdStep 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