Cursor rule

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