3ac66feba2
gitignore 의 *.md / .claude/ 차단을 풀어 다음 파일을 git 으로 추적. - /CLAUDE.md, /AGENTS.md (루트 에이전트 가이드) - .agents/**/*.md (skills 문서 95개) - .claude/settings.json (Claude Code 프로젝트 설정) .claude/worktrees/ 는 git worktree 메타이므로 신규 ignore 라인으로 제외. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
100 lines
2.5 KiB
Markdown
100 lines
2.5 KiB
Markdown
---
|
|
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.
|