556
Bn
bees-nest / files
bees-nest / .opencode / skills / vercel-react-best-practices / rules / async-suspense-boundaries.md
2.5 KB
1--- 2title: Strategic Suspense Boundaries 3impact: HIGH 4impactDescription: faster initial paint 5tags: async, suspense, streaming, layout-shift 6--- 7 8## Strategic Suspense Boundaries 9 10Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads. 11 12**Incorrect (wrapper blocked by data fetching):** 13 14```tsx 15async function Page() { 16 const data = await fetchData() // Blocks entire page 17 18 return ( 19 <div> 20 <div>Sidebar</div> 21 <div>Header</div> 22 <div> 23 <DataDisplay data={data} /> 24 </div> 25 <div>Footer</div> 26 </div> 27 ) 28} 29``` 30 31The entire layout waits for data even though only the middle section needs it. 32 33**Correct (wrapper shows immediately, data streams in):** 34 35```tsx 36function Page() { 37 return ( 38 <div> 39 <div>Sidebar</div> 40 <div>Header</div> 41 <div> 42 <Suspense fallback={<Skeleton />}> 43 <DataDisplay /> 44 </Suspense> 45 </div> 46 <div>Footer</div> 47 </div> 48 ) 49} 50 51async function DataDisplay() { 52 const data = await fetchData() // Only blocks this component 53 return <div>{data.content}</div> 54} 55``` 56 57Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data. 58 59**Alternative (share promise across components):** 60 61```tsx 62function Page() { 63 // Start fetch immediately, but don't await 64 const dataPromise = fetchData() 65 66 return ( 67 <div> 68 <div>Sidebar</div> 69 <div>Header</div> 70 <Suspense fallback={<Skeleton />}> 71 <DataDisplay dataPromise={dataPromise} /> 72 <DataSummary dataPromise={dataPromise} /> 73 </Suspense> 74 <div>Footer</div> 75 </div> 76 ) 77} 78 79function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) { 80 const data = use(dataPromise) // Unwraps the promise 81 return <div>{data.content}</div> 82} 83 84function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) { 85 const data = use(dataPromise) // Reuses the same promise 86 return <div>{data.summary}</div> 87} 88``` 89 90Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together. 91 92**When NOT to use this pattern:** 93 94- Critical data needed for layout decisions (affects positioning) 95- SEO-critical content above the fold 96- Small, fast queries where suspense overhead isn't worth it 97- When you want to avoid layout shift (loading → content jump) 98 99**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.