Cursor rule

1---
2alwaysApply: false
3---
4 
5## Defer Non-Critical Work with requestIdleCallback
6 
7**Impact: MEDIUM (keeps UI responsive during background tasks)**
8 
9Use `requestIdleCallback()` to schedule non-critical work during browser idle periods. This keeps the main thread free for user interactions and animations, reducing jank and improving perceived performance.
10 
11**Incorrect (blocks main thread during user interaction):**
12 
13```typescript
14function handleSearch(query: string) {
15  const results = searchItems(query)
16  setResults(results)
17 
18  // These block the main thread immediately
19  analytics.track('search', { query })
20  saveToRecentSearches(query)
21  prefetchTopResults(results.slice(0, 3))
22}
23```
24 
25**Correct (defers non-critical work to idle time):**
26 
27```typescript
28function handleSearch(query: string) {
29  const results = searchItems(query)
30  setResults(results)
31 
32  // Defer non-critical work to idle periods
33  requestIdleCallback(() => {
34    analytics.track('search', { query })
35  })
36 
37  requestIdleCallback(() => {
38    saveToRecentSearches(query)
39  })
40 
41  requestIdleCallback(() => {
42    prefetchTopResults(results.slice(0, 3))
43  })
44}
45```
46 
47**With timeout for required work:**
48 
49```typescript
50// Ensure analytics fires within 2 seconds even if browser stays busy
51requestIdleCallback(
52  () => analytics.track('page_view', { path: location.pathname }),
53  { timeout: 2000 }
54)
55```
56 
57**Chunking large tasks:**
58 
59```typescript
60function processLargeDataset(items: Item[]) {
61  let index = 0
62 
63  function processChunk(deadline: IdleDeadline) {
64    // Process items while we have idle time (aim for <50ms chunks)
65    while (index < items.length && deadline.timeRemaining() > 0) {
66      processItem(items[index])
67      index++
68    }
69 
70    // Schedule next chunk if more items remain
71    if (index < items.length) {
72      requestIdleCallback(processChunk)
73    }
74  }
75 
76  requestIdleCallback(processChunk)
77}
78```
79 
80**With fallback for unsupported browsers:**
81 
82```typescript
83const scheduleIdleWork = window.requestIdleCallback ?? ((cb: () => void) => setTimeout(cb, 1))
84 
85scheduleIdleWork(() => {
86  // Non-critical work
87})
88```
89 
90**When to use:**
91 
92- Analytics and telemetry
93- Saving state to localStorage/IndexedDB
94- Prefetching resources for likely next actions
95- Processing non-urgent data transformations
96- Lazy initialization of non-critical features
97 
98**When NOT to use:**
99 
100- User-initiated actions that need immediate feedback
101- Rendering updates the user is waiting for
102- Time-sensitive operations
103