---
name: ck-react-best-practices
description: React and Next.js performance optimization from Vercel Engineering. Use when writing, reviewing, or refactoring React components, data fetching, bundle optimization, or fixing performance issues.
---

# React Best Practices (Vercel)

45 prioritized rules across 8 categories for React and Next.js performance.

## When to Use

- Writing new React components or Next.js pages
- Implementing data fetching (client or server-side)
- Reviewing code for performance issues
- Optimizing bundle size or load times
- Refactoring existing React/Next.js code

## Don't Use When

- Working with non-React frameworks (Vue, Svelte, Angular)
- Pure Node.js backend code without React

## Rules by Priority

### 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
- `async-suspense-boundaries` — use Suspense to stream content

### 2. Bundle Size (CRITICAL)
- `bundle-barrel-imports` — import directly, avoid barrel files
- `bundle-dynamic-imports` — use next/dynamic for heavy components
- `bundle-defer-third-party` — load analytics after hydration
- `bundle-conditional` — load modules only when feature activated
- `bundle-preload` — preload on hover/focus for perceived speed

### 3. Server-Side Performance (HIGH)
- `server-cache-react` — use React.cache() for per-request dedup
- `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
- `server-after-nonblocking` — use after() for non-blocking ops

### 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-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-set-map-lookups` — use Set/Map for O(1) lookups
- `js-early-exit` — return early from functions
- `js-hoist-regexp` — hoist RegExp creation outside loops

### 8. Advanced Patterns (LOW)
- `advanced-event-handler-refs` — store event handlers in refs
- `advanced-use-latest` — useLatest for stable callback refs

## Full Reference

Complete guide with code examples: `AGENTS.md`

Individual rule files: `rules/<rule-name>.md`