feat: add react-best-practices power

README.md

@@ -83,6 +83,13 @@ Documentation is available at https://kiro.dev/docs/powers/
 
 ---
 
+### react-best-practices
+**React Best Practices** - React and Next.js performance optimization guidelines from Vercel Engineering. 45 rules across 8 categories, prioritized by impact from CRITICAL to LOW.
+
+**MCP Servers:** None (Knowledge Base Power)
+
+---
+
 ### saas-builder
 **SaaS Builder** - Build production-ready multi-tenant SaaS applications with serverless architecture, integrated billing, and enterprise-grade security.
 

react-best-practices/POWER.md

@@ -0,0 +1,153 @@
+---
+name: "react-best-practices"
+displayName: "React Best Practices"
+description: "React and Next.js performance optimization guidelines from Vercel Engineering. 45 rules across 8 categories, prioritized by impact from CRITICAL to LOW."
+keywords: ["react", "nextjs", "performance", "optimization", "bundle", "waterfall", "re-render", "ssr", "vercel"]
+author: "Vercel"
+---
+
+# React Best Practices
+
+## Overview
+
+Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel Engineering. Contains 45 rules across 8 categories, prioritized by impact to guide code review, refactoring, and code generation.
+
+**Core Principle:** Performance work should start at the top of the stack. If a request waterfall adds 600ms of waiting time, optimizing `useMemo` calls won't help. Fix waterfalls first, then bundle size, then work down the priority list.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new React components or Next.js pages
+- Implementing data fetching (client or server-side)
+- Reviewing code for performance issues
+- Refactoring existing React/Next.js code
+- Optimizing bundle size or load times
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix | Rules |
+|----------|----------|--------|--------|-------|
+| 1 | Eliminating Waterfalls | CRITICAL | `async-` | 5 |
+| 2 | Bundle Size Optimization | CRITICAL | `bundle-` | 5 |
+| 3 | Server-Side Performance | HIGH | `server-` | 5 |
+| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` | 2 |
+| 5 | Re-render Optimization | MEDIUM | `rerender-` | 7 |
+| 6 | Rendering Performance | MEDIUM | `rendering-` | 7 |
+| 7 | JavaScript Performance | LOW-MEDIUM | `js-` | 12 |
+| 8 | Advanced Patterns | LOW | `advanced-` | 2 |
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+steering/async-parallel.md
+steering/bundle-barrel-imports.md
+```
+
+For the complete guide with all rules expanded: `steering/full-guide.md`
+
+## Available Steering Files
+
+Each rule is available as a separate steering file. Use `readSteering` with the rule name to get detailed explanations and code examples.
+
+- **full-guide** - Complete compiled document with all 45 rules (2,200+ lines)
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- **async-defer-await** - Move await into branches where actually used
+- **async-parallel** - Use Promise.all() for independent operations
+- **async-dependencies** - Use better-all for partial dependencies
+- **async-api-routes** - Start promises early, await late in API routes
+- **async-suspense-boundaries** - Use Suspense to stream content
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- **bundle-barrel-imports** - Import directly, avoid barrel files
+- **bundle-dynamic-imports** - Use next/dynamic for heavy components
+- **bundle-defer-third-party** - Load analytics/logging after hydration
+- **bundle-conditional** - Load modules only when feature is activated
+- **bundle-preload** - Preload on hover/focus for perceived speed
+
+### 3. Server-Side Performance (HIGH)
+
+- **server-cache-react** - Use React.cache() for per-request deduplication
+- **server-cache-lru** - Use LRU cache for cross-request caching
+- **server-serialization** - Minimize data passed to client components
+- **server-parallel-fetching** - Restructure components to parallelize fetches
+- **server-after-nonblocking** - Use after() for non-blocking operations
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- **client-swr-dedup** - Use SWR for automatic request deduplication
+- **client-event-listeners** - Deduplicate global event listeners
+
+### 5. Re-render Optimization (MEDIUM)
+
+- **rerender-defer-reads** - Don't subscribe to state only used in callbacks
+- **rerender-memo** - Extract expensive work into memoized components
+- **rerender-dependencies** - Use primitive dependencies in effects
+- **rerender-derived-state** - Subscribe to derived booleans, not raw values
+- **rerender-functional-setstate** - Use functional setState for stable callbacks
+- **rerender-lazy-state-init** - Pass function to useState for expensive values
+- **rerender-transitions** - Use startTransition for non-urgent updates
+
+### 6. Rendering Performance (MEDIUM)
+
+- **rendering-animate-svg-wrapper** - Animate div wrapper, not SVG element
+- **rendering-content-visibility** - Use content-visibility for long lists
+- **rendering-hoist-jsx** - Extract static JSX outside components
+- **rendering-svg-precision** - Reduce SVG coordinate precision
+- **rendering-hydration-no-flicker** - Use inline script for client-only data
+- **rendering-activity** - Use Activity component for show/hide
+- **rendering-conditional-render** - Use ternary, not && for conditionals
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+
+- **js-batch-dom-css** - Group CSS changes via classes or cssText
+- **js-index-maps** - Build Map for repeated lookups
+- **js-cache-property-access** - Cache object properties in loops
+- **js-cache-function-results** - Cache function results in module-level Map
+- **js-cache-storage** - Cache localStorage/sessionStorage reads
+- **js-combine-iterations** - Combine multiple filter/map into one loop
+- **js-length-check-first** - Check array length before expensive comparison
+- **js-early-exit** - Return early from functions
+- **js-hoist-regexp** - Hoist RegExp creation outside loops
+- **js-min-max-loop** - Use loop for min/max instead of sort
+- **js-set-map-lookups** - Use Set/Map for O(1) lookups
+- **js-tosorted-immutable** - Use toSorted() for immutability
+
+### 8. Advanced Patterns (LOW)
+
+- **advanced-event-handler-refs** - Store event handlers in refs
+- **advanced-use-latest** - useLatest for stable callback refs
+
+## Best Practices
+
+### ✅ Do:
+- Start with CRITICAL rules (waterfalls, bundle size) before micro-optimizations
+- Use `Promise.all()` for independent async operations
+- Import directly from source files, not barrel files
+- Use `next/dynamic` for heavy components not needed on initial render
+- Use `React.cache()` for per-request deduplication on the server
+- Use SWR for client-side data fetching with automatic deduplication
+
+### ❌ Don't:
+- Optimize `useMemo`/`useCallback` before fixing waterfalls
+- Import from barrel files (`import { X } from 'library'`)
+- Load analytics/tracking scripts before hydration
+- Subscribe to entire objects when you only need a derived boolean
+- Use `&&` for conditional rendering (use ternary instead)
+
+## References
+
+- [React Documentation](https://react.dev)
+- [Next.js Documentation](https://nextjs.org)
+- [SWR Documentation](https://swr.vercel.app)
+- [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+- [Source Repository](https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices)
+
+---
+
+**License:** MIT  
+**Original Author:** [@shuding](https://x.com/shuding) at Vercel

react-best-practices/steering/advanced-event-handler-refs.md

@@ -0,0 +1,55 @@
+---
+title: Store Event Handlers in Refs
+impact: LOW
+impactDescription: stable subscriptions
+tags: advanced, hooks, refs, event-handlers, optimization
+---
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: () => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: () => void) {
+  const handlerRef = useRef(handler)
+  useEffect(() => {
+    handlerRef.current = handler
+  }, [handler])
+
+  useEffect(() => {
+    const listener = () => handlerRef.current()
+    window.addEventListener(event, listener)
+    return () => window.removeEventListener(event, listener)
+  }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: () => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.

react-best-practices/steering/advanced-use-latest.md

@@ -0,0 +1,49 @@
+---
+title: useLatest for Stable Callback Refs
+impact: LOW
+impactDescription: prevents effect re-runs
+tags: advanced, hooks, useLatest, refs, optimization
+---
+
+## useLatest for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Implementation:**
+
+```typescript
+function useLatest<T>(value: T) {
+  const ref = useRef(value)
+  useEffect(() => {
+    ref.current = value
+  }, [value])
+  return ref
+}
+```
+
+**Incorrect (effect re-runs on every callback change):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+```
+
+**Correct (stable effect, fresh callback):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchRef = useLatest(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchRef.current(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```

react-best-practices/steering/async-api-routes.md

@@ -0,0 +1,38 @@
+---
+title: Prevent Waterfall Chains in API Routes
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: api-routes, server-actions, waterfalls, parallelization
+---
+
+## Prevent Waterfall Chains in API Routes
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect (config waits for auth, data waits for both):**
+
+```typescript
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+```
+
+**Correct (auth and config start immediately):**
+
+```typescript
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id)
+  ])
+  return Response.json({ data, config })
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).

react-best-practices/steering/async-defer-await.md

@@ -0,0 +1,80 @@
+---
+title: Defer Await Until Needed
+impact: HIGH
+impactDescription: avoids blocking unused code paths
+tags: async, await, conditional, optimization
+---
+
+## Defer Await Until Needed
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect (blocks both branches):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true }
+  }
+
+  // Only this branch uses userData
+  return processUserData(userData)
+}
+```
+
+**Correct (only blocks when needed):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true }
+  }
+
+  // Fetch only when needed
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+**Another example (early return optimization):**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId)
+  const resource = await getResource(resourceId)
+
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+
+  return await updateResourceData(resource, permissions)
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId)
+
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+
+  const permissions = await fetchPermissions(userId)
+
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+
+  return await updateResourceData(resource, permissions)
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.