@codihaus/claude-skills 1.6.18 → 1.6.20

package/knowledge/stacks/react/_index.md

@@ -571,9 +571,30 @@ When reviewing React code:
 - useDeferredValue (defer updates for performance)
 - useSyncExternalStore (external store integration)
 
+## Advanced Performance Patterns
+
+**See `references/performance.md` for comprehensive optimization guide covering**:
+- Re-render optimization (functional setState, lazy initialization, transitions)
+- Rendering performance (hoisting, content-visibility, hydration)
+- Client-side optimization (passive listeners, storage caching)
+- JavaScript performance (index maps, Set/Map, toSorted)
+- Advanced patterns (useLatest, event handler refs)
+
+**Key takeaways**:
+- Use functional setState to prevent stale closures
+- Lazy initialize expensive state with function
+- Mark non-urgent updates with startTransition
+- Hoist static JSX outside render
+- Use content-visibility for long lists
+- Cache storage API calls in memory
+- Build index Maps for repeated lookups
+- Use toSorted() instead of sort() for immutability
+
 ## Resources
 
 - [React Docs](https://react.dev) - Official documentation
 - [React DevTools](https://react.dev/learn/react-developer-tools) - Browser extension
 - [Rules of Hooks](https://react.dev/reference/rules/rules-of-hooks) - Hook constraints
 - [React TypeScript Cheatsheet](https://react-typescript-cheatsheet.netlify.app) - TS patterns
+- [Vercel React Best Practices](https://github.com/vercel/react-best-practices) - Performance patterns
+- `references/performance.md` - Detailed optimization guide

package/knowledge/stacks/react/references/performance.md

@@ -0,0 +1,573 @@
+# React Performance Optimization
+
+> Critical performance patterns from Vercel Engineering
+
+## Re-render Optimization
+
+### Functional setState Updates
+
+**Impact**: Prevents stale closures, enables stable callbacks
+
+Always use functional updates when state depends on current state:
+
+```typescript
+// ❌ Incorrect: stale closure risk
+const removeItem = useCallback((id: string) => {
+  setItems(items.filter(item => item.id !== id))
+}, [])  // Missing items dependency - STALE
+
+// ✅ Correct: always uses latest state
+const removeItem = useCallback((id: string) => {
+  setItems(curr => curr.filter(item => item.id !== id))
+}, [])  // Safe and stable
+```
+
+### Lazy State Initialization
+
+**Impact**: Expensive initial computation runs only once
+
+Pass function to `useState` for expensive initial values:
+
+```typescript
+// ❌ Incorrect: runs on every render
+const [settings, setSettings] = useState(
+  JSON.parse(localStorage.getItem('settings') || '{}')
+)
+
+// ✅ Correct: runs only once
+const [settings, setSettings] = useState(() => {
+  const stored = localStorage.getItem('settings')
+  return stored ? JSON.parse(stored) : {}
+})
+```
+
+### Use Transitions for Non-Urgent Updates
+
+**Impact**: Maintains UI responsiveness
+
+Mark frequent, non-urgent updates as transitions:
+
+```typescript
+import { useTransition } from 'react'
+
+function SearchResults() {
+  const [isPending, startTransition] = useTransition()
+  const [results, setResults] = useState([])
+
+  function handleSearch(query: string) {
+    startTransition(() => {
+      // Non-urgent: heavy filtering/search
+      setResults(expensiveSearch(query))
+    })
+  }
+
+  return (
+    <>
+      <input onChange={e => handleSearch(e.target.value)} />
+      {isPending && <Spinner />}
+      <Results data={results} />
+    </>
+  )
+}
+```
+
+### Defer State Reads to Usage Point
+
+**Impact**: Avoids unnecessary re-renders
+
+Don't subscribe to state if only read in callbacks:
+
+```typescript
+// ❌ Incorrect: component re-renders on every URL change
+function Component() {
+  const searchParams = useSearchParams()  // Re-renders on change
+
+  const handleSubmit = () => {
+    const query = searchParams.get('q')  // Used only here
+    submitForm(query)
+  }
+
+  return <button onClick={handleSubmit}>Submit</button>
+}
+
+// ✅ Correct: no re-renders, read directly in callback
+function Component() {
+  const handleSubmit = () => {
+    const query = new URLSearchParams(window.location.search).get('q')
+    submitForm(query)
+  }
+
+  return <button onClick={handleSubmit}>Submit</button>
+}
+```
+
+### Extract to Memoized Components
+
+**Impact**: Prevents unnecessary re-renders of expensive subtrees
+
+```typescript
+// ❌ Incorrect: entire list re-renders on count change
+function Page() {
+  const [count, setCount] = useState(0)
+  return (
+    <div>
+      <button onClick={() => setCount(c => c + 1)}>{count}</button>
+      <ExpensiveList items={items} /> {/* Re-renders unnecessarily */}
+    </div>
+  )
+}
+
+// ✅ Correct: list doesn't re-render
+const MemoizedList = memo(ExpensiveList)
+
+function Page() {
+  const [count, setCount] = useState(0)
+  return (
+    <div>
+      <button onClick={() => setCount(c => c + 1)}>{count}</button>
+      <MemoizedList items={items} />
+    </div>
+  )
+}
+```
+
+### Narrow Effect Dependencies
+
+**Impact**: Reduces effect re-runs
+
+Extract only needed properties instead of whole objects:
+
+```typescript
+// ❌ Incorrect: effect runs on any user change
+useEffect(() => {
+  logUserActivity(user.id)
+}, [user])  // user object changes often
+
+// ✅ Correct: effect only runs when ID changes
+useEffect(() => {
+  logUserActivity(user.id)
+}, [user.id])  // Stable value
+```
+
+### Subscribe to Derived State
+
+**Impact**: Avoids storing and synchronizing computed values
+
+```typescript
+// ❌ Incorrect: derived state in useState (sync issue)
+const [items, setItems] = useState([])
+const [count, setCount] = useState(0)
+
+useEffect(() => {
+  setCount(items.length)  // Sync issue!
+}, [items])
+
+// ✅ Correct: compute during render
+const [items, setItems] = useState([])
+const count = items.length  // Always in sync
+```
+
+## Rendering Performance
+
+### Hoist Static JSX Elements
+
+**Impact**: Prevents recreation on every render
+
+```typescript
+// ❌ Incorrect: creates new object on every render
+function Component({ title }) {
+  return (
+    <div>
+      <Icon name="check" color="green" />  {/* New object every render */}
+      {title}
+    </div>
+  )
+}
+
+// ✅ Correct: created once
+const CheckIcon = <Icon name="check" color="green" />
+
+function Component({ title }) {
+  return (
+    <div>
+      {CheckIcon}
+      {title}
+    </div>
+  )
+}
+```
+
+### CSS content-visibility for Long Lists
+
+**Impact**: 10× faster initial render
+
+Browser skips layout/paint for off-screen items:
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;  /* Estimated height */
+}
+```
+
+### Use Explicit Conditional Rendering
+
+**Impact**: Prevents rendering unwanted values
+
+Use ternary when condition can be `0` or `NaN`:
+
+```typescript
+// ❌ Incorrect: renders "0" when count is 0
+{count && <div>{count} items</div>}
+
+// ✅ Correct: renders nothing when 0
+{count > 0 && <div>{count} items</div>}
+// or
+{count ? <div>{count} items</div> : null}
+```
+
+### Prevent Hydration Mismatch Without Flickering
+
+**Impact**: No FOUC (Flash of Unstyled Content)
+
+Use synchronous inline script:
+
+```tsx
+function ThemeWrapper({ children }) {
+  return (
+    <>
+      <div id="theme-wrapper">{children}</div>
+      <script dangerouslySetInnerHTML={{__html: `
+        (function() {
+          try {
+            var theme = localStorage.getItem('theme') || 'light';
+            var el = document.getElementById('theme-wrapper');
+            if (el) el.className = theme;
+          } catch (e) {}
+        })();
+      `}} />
+    </>
+  )
+}
+```
+
+### Animate SVG Wrapper Instead of Element
+
+**Impact**: Reduces paint complexity
+
+```typescript
+// ❌ Incorrect: animates SVG element directly
+<svg style={{ transform: `translateX(${x}px)` }}>
+  <path d="..." />
+</svg>
+
+// ✅ Correct: animate wrapper div
+<div style={{ transform: `translateX(${x}px)` }}>
+  <svg><path d="..." /></svg>
+</div>
+```
+
+### Activity Component for Show/Hide
+
+**Impact**: Prevents layout thrashing
+
+```typescript
+// ❌ Incorrect: removes from DOM (layout thrash)
+{isVisible && <ExpensiveComponent />}
+
+// ✅ Correct: uses visibility (keeps layout)
+<div style={{ visibility: isVisible ? 'visible' : 'hidden' }}>
+  <ExpensiveComponent />
+</div>
+```
+
+## Client-Side Optimization
+
+### Use Passive Event Listeners
+
+**Impact**: Eliminates scroll delay
+
+Add `{ passive: true }` to touch/wheel events:
+
+```typescript
+useEffect(() => {
+  const handleScroll = (e: Event) => {
+    // No preventDefault() call
+    updateScrollPosition()
+  }
+
+  // ✅ Passive listener - doesn't block scrolling
+  window.addEventListener('scroll', handleScroll, { passive: true })
+
+  return () => {
+    window.removeEventListener('scroll', handleScroll, { passive: true } as any)
+  }
+}, [])
+```
+
+### Deduplicate Global Event Listeners
+
+**Impact**: N instances = 1 listener instead of N
+
+Use shared hook for global events:
+
+```typescript
+// ❌ Incorrect: N listeners for N components
+function Component() {
+  useEffect(() => {
+    const handler = () => console.log('resize')
+    window.addEventListener('resize', handler)
+    return () => window.removeEventListener('resize', handler)
+  }, [])
+}
+
+// ✅ Correct: 1 listener shared across all instances
+import { useSWRSubscription } from 'swr/subscription'
+
+function useWindowSize() {
+  return useSWRSubscription('window-size', (key, { next }) => {
+    const handler = () => next(null, {
+      width: window.innerWidth,
+      height: window.innerHeight
+    })
+
+    window.addEventListener('resize', handler)
+    handler() // Initial value
+
+    return () => window.removeEventListener('resize', handler)
+  })
+}
+```
+
+### Cache Storage API Calls
+
+**Impact**: Avoids synchronous I/O on every access
+
+```typescript
+// ❌ Incorrect: reads from localStorage on every access
+function useSettings() {
+  const [settings, setSettings] = useState(() => {
+    return JSON.parse(localStorage.getItem('settings') || '{}')
+  })
+
+  // Every time this runs, reads from localStorage
+  const value = localStorage.getItem('key')
+}
+
+// ✅ Correct: cache in memory
+const settingsCache = new Map<string, any>()
+
+function getCachedSetting(key: string) {
+  if (settingsCache.has(key)) {
+    return settingsCache.get(key)
+  }
+
+  const value = localStorage.getItem(key)
+  const parsed = value ? JSON.parse(value) : null
+  settingsCache.set(key, parsed)
+  return parsed
+}
+
+// Invalidate on storage events
+window.addEventListener('storage', (e) => {
+  if (e.key) settingsCache.delete(e.key)
+})
+```
+
+## JavaScript Performance
+
+### Build Index Maps for Repeated Lookups
+
+**Impact**: O(n×m) → O(n+m), 1M ops → 2K ops
+
+```typescript
+// ❌ Incorrect: O(n) per lookup
+return orders.map(order => ({
+  ...order,
+  user: users.find(u => u.id === order.userId)  // O(n) each time
+}))
+
+// ✅ Correct: O(1) per lookup
+const userById = new Map(users.map(u => [u.id, u]))
+return orders.map(order => ({
+  ...order,
+  user: userById.get(order.userId)  // O(1)
+}))
+```
+
+### Cache Property Access in Loops
+
+**Impact**: Avoids repeated property lookups
+
+```typescript
+// ❌ Incorrect: repeated access
+for (let i = 0; i < items.length; i++) {
+  // items.length evaluated each iteration
+}
+
+// ✅ Correct: cached
+const len = items.length
+for (let i = 0; i < len; i++) {
+  // Faster
+}
+```
+
+### Hoist RegExp Creation
+
+**Impact**: Avoids creating regex on every call
+
+```typescript
+// ❌ Incorrect: creates new RegExp every call
+function validate(email: string) {
+  return /^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$/.test(email)
+}
+
+// ✅ Correct: created once
+const EMAIL_REGEX = /^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$/
+
+function validate(email: string) {
+  return EMAIL_REGEX.test(email)
+}
+```
+
+### Use toSorted() Instead of sort()
+
+**Impact**: Prevents mutation bugs in React state
+
+```typescript
+// ❌ Incorrect: mutates array
+setItems(items.sort((a, b) => a - b))  // MUTATION BUG
+
+// ✅ Correct: creates new array (Chrome 110+)
+setItems(items.toSorted((a, b) => a - b))
+
+// ✅ Alternative: spread + sort
+setItems([...items].sort((a, b) => a - b))
+```
+
+### Combine Multiple Array Iterations
+
+**Impact**: O(3n) → O(n)
+
+```typescript
+// ❌ Incorrect: 3 passes
+const filtered = items.filter(x => x.active)
+const mapped = filtered.map(x => x.value)
+const result = mapped.slice(0, 10)
+
+// ✅ Correct: 1 pass
+const result = items
+  .filter(x => x.active)
+  .map(x => x.value)
+  .slice(0, 10)
+
+// ✅ Even better: reduce for complex transforms
+const result = items.reduce((acc, item) => {
+  if (item.active && acc.length < 10) {
+    acc.push(item.value)
+  }
+  return acc
+}, [] as number[])
+```
+
+### Use Set/Map for O(1) Lookups
+
+**Impact**: O(n) → O(1)
+
+```typescript
+// ❌ Incorrect: O(n) lookup
+const isAllowed = (id: string) => allowedIds.includes(id)
+
+// ✅ Correct: O(1) lookup
+const allowedSet = new Set(allowedIds)
+const isAllowed = (id: string) => allowedSet.has(id)
+```
+
+### Early Length Check for Array Comparisons
+
+**Impact**: Avoids unnecessary iteration
+
+```typescript
+// ❌ Incorrect: iterates even when lengths differ
+function arraysEqual(a: any[], b: any[]) {
+  return a.every((item, i) => item === b[i])
+}
+
+// ✅ Correct: check length first
+function arraysEqual(a: any[], b: any[]) {
+  if (a.length !== b.length) return false
+  return a.every((item, i) => item === b[i])
+}
+```
+
+## Advanced Patterns
+
+### Store Event Handlers in Refs
+
+**Impact**: Stable references without useCallback
+
+```typescript
+// ❌ Incorrect: needs dependencies
+const handleClick = useCallback(() => {
+  doSomething(prop1, prop2)
+}, [prop1, prop2])  // Changes often
+
+// ✅ Correct: always stable
+const handleClickRef = useRef<() => void>()
+handleClickRef.current = () => {
+  doSomething(prop1, prop2)
+}
+
+const handleClick = useCallback(() => {
+  handleClickRef.current?.()
+}, [])  // Never changes
+```
+
+### useLatest for Stable Callback Refs
+
+**Impact**: Avoids stale closures with stable identity
+
+```typescript
+function useLatest<T>(value: T) {
+  const ref = useRef(value)
+  useEffect(() => {
+    ref.current = value
+  })
+  return ref
+}
+
+// Usage
+function Component({ onEvent }) {
+  const onEventRef = useLatest(onEvent)
+
+  useEffect(() => {
+    const handler = () => onEventRef.current()
+    window.addEventListener('resize', handler)
+    return () => window.removeEventListener('resize', handler)
+  }, [])  // Empty deps, always uses latest
+}
+```
+
+## Anti-Patterns to Avoid
+
+1. ❌ Non-functional setState (stale closures)
+2. ❌ Missing lazy initialization for expensive initial state
+3. ❌ State reads in render when only used in callbacks
+4. ❌ Creating RegExp/objects in render
+5. ❌ Non-passive scroll/touch event listeners
+6. ❌ Multiple array iterations when one would suffice
+7. ❌ Using `&&` for conditional rendering with numbers
+8. ❌ Direct `.sort()` mutation in React state
+9. ❌ Storing derived values in state
+10. ❌ Not extracting expensive components to memo
+
+## React Compiler Note
+
+Many of these optimizations become automatic with React Compiler:
+- Auto-memoization of expensive computations
+- Automatic extraction of stable dependencies
+- Smart re-render optimization
+
+However, architectural patterns (lazy state init, transitions, content-visibility) still require manual implementation.
+
+**Reference**: [Vercel React Best Practices](https://github.com/vercel/react-best-practices)