--- frontmattername: react-best-practices
description: |
57 React/Next.js performance rules from Vercel. Covers waterfalls, bundle size, re-renders.
Triggers: "React performance", "optimize Next.js", "bundle size", "re-renders".
license: MIT
React Best Practices
Performance optimization guide for React and Next.js applications. Originally from Vercel Engineering.
Rule Categories by Priority
| Priority | Category | Impact | Rules | Prefix |
|---|
| 1 | Eliminating Waterfalls | CRITICAL | 5 | async- |
| 2 | Bundle Size Optimization | CRITICAL | 5 | bundle- |
| 3 | Server-Side Performance | HIGH | 7 | server- |
| 4 | Client-Side Data Fetching | MEDIUM-HIGH | 4 | client- |
| 5 | Re-render Optimization | MEDIUM | 12 | rerender- |
| 6 | Rendering Performance | MEDIUM | 9 | rendering- |
| 7 | JavaScript Performance | LOW-MEDIUM | 12 | js- |
| 8 | Advanced Patterns | LOW | 3 | advanced- |
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
CRITICAL Priority Rules
1. Eliminating Waterfalls
Sequential data fetching is the #1 performance killer. Fix by parallelizing.
| Rule | Description |
|---|
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
Every KB costs ~1ms on 3G. Reduce bundle size aggressively.
| Rule | Description |
|---|
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 |
HIGH Priority Rules
3. Server-Side Performance
| Rule | Description |
|---|
server-auth-actions | Authenticate server actions like API routes |
server-cache-react | Use React.cache() for per-request deduplication |
server-cache-lru | Use LRU cache for cross-request caching |
server-dedup-props | Avoid duplicate serialization in RSC props |
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 |
MEDIUM Priority Rules
4. Client-Side Data Fetching
| Rule | Description |
|---|
client-swr-dedup | Use SWR for automatic request deduplication |
client-event-listeners | Deduplicate global event listeners |
client-passive-event-listeners | Use passive listeners for scroll |
client-localstorage-schema | Version and minimize localStorage data |
5. Re-render Optimization
| Rule | Description |
|---|
rerender-defer-reads | Don't subscribe to state only used in callbacks |
rerender-memo | Extract expensive work into memoized components |
rerender-memo-with-default-value | Hoist default non-primitive props |
rerender-dependencies | Use primitive dependencies in effects |
rerender-derived-state | Subscribe to derived booleans, not raw values |
rerender-derived-state-no-effect | Derive state during render, not effects |
rerender-functional-setstate | Use functional setState for stable callbacks |
rerender-lazy-state-init | Pass function to useState for expensive values |
rerender-simple-expression-in-memo | Avoid memo for simple primitives |
rerender-move-effect-to-event | Put interaction logic in event handlers |
rerender-transitions | Use startTransition for non-urgent updates |
rerender-use-ref-transient-values | Use refs for transient frequent values |
6. Rendering Performance
| Rule | Description |
|---|
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-hydration-suppress-warning | Suppress expected mismatches |
rendering-activity | Use Activity component for show/hide |
rendering-conditional-render | Use ternary, not && for conditionals |
rendering-usetransition-loading | Prefer useTransition for loading state |
LOW Priority Rules
7. JavaScript Performance
| Rule | Description |
|---|
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
| Rule | Description |
|---|
advanced-event-handler-refs | Store event handlers in refs |
advanced-init-once | Initialize app once per app load |
advanced-use-latest | useLatest for stable callback refs |
How to Use Rules
Each rule file in rules/ contains:
- •Brief explanation of why it matters
- •Incorrect code example with explanation
- •Correct code example with explanation
- •Additional context and references
Example rule path: ./rules/async-parallel.md
For the complete compiled guide: ./AGENTS.md
Related Skills
After performance optimization:
- •
component-builder to build new components with best practices
- •
design-audit to check overall page quality