react-best-practices

---
name: react-best-practices
description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
---

# React Best Practices

## Overview

Comprehensive performance optimization guide for React and Next.js applications, containing 40+ rules across 8 categories. Rules are prioritized by impact to guide automated refactoring and code generation.

## 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

## Priority-Ordered Guidelines

Rules are prioritized by impact:

| Priority | Category | Impact |
|----------|----------|--------|
| 1 | Eliminating Waterfalls | CRITICAL |
| 2 | Bundle Size Optimization | CRITICAL |
| 3 | Server-Side Performance | HIGH |
| 4 | Client-Side Data Fetching | MEDIUM-HIGH |
| 5 | Re-render Optimization | MEDIUM |
| 6 | Rendering Performance | MEDIUM |
| 7 | JavaScript Performance | LOW-MEDIUM |
| 8 | Advanced Patterns | LOW |

## Quick Reference

### Critical Patterns (Apply First)

**Eliminate Waterfalls:**
- Defer await until needed (move into branches)
- Use `Promise.all()` for independent async operations
- Start promises early, await late
- Use `better-all` for partial dependencies
- Use Suspense boundaries to stream content

**Reduce Bundle Size:**
- Avoid barrel file imports (import directly from source)
- Use `next/dynamic` for heavy components
- Defer non-critical third-party libraries
- Preload based on user intent

### High-Impact Server Patterns

- Use `React.cache()` for per-request deduplication
- Use LRU cache for cross-request caching
- Minimize serialization at RSC boundaries
- Parallelize data fetching with component composition

### Medium-Impact Client Patterns

- Use SWR for automatic request deduplication
- Defer state reads to usage point
- Use lazy state initialization for expensive values
- Use derived state subscriptions
- Apply `startTransition` for non-urgent updates

### Rendering Patterns

- Animate SVG wrappers, not SVG elements directly
- Use `content-visibility: auto` for long lists
- Prevent hydration mismatch with inline scripts
- Use explicit conditional rendering (`? :` not `&&`)

### JavaScript Patterns

- Batch DOM CSS changes via classes
- Build index maps for repeated lookups
- Cache repeated function calls
- Use `toSorted()` instead of `sort()` for immutability
- Early length check for array comparisons

## References

Full documentation with code examples is available in:

- `references/react-performance-guidelines.md` - Complete guide with all patterns
- `references/rules/` - Individual rule files organized by category

To look up a specific pattern, grep the rules directory:
```
grep -l "suspense" references/rules/
grep -l "barrel" references/rules/
grep -l "swr" references/rules/
```

## Rule Categories in `references/rules/`

- `async-*` - Waterfall elimination patterns
- `bundle-*` - Bundle size optimization
- `server-*` - Server-side performance
- `client-*` - Client-side data fetching
- `rerender-*` - Re-render optimization
- `rendering-*` - DOM rendering performance
- `js-*` - JavaScript micro-optimizations
- `advanced-*` - Advanced patterns

• SKILL.md 3 KB
• references/react-performance-guidelines.md 48 KB
• references/rules/_sections.md 2 KB
• references/rules/_template.md 1 KB
• references/rules/advanced-event-handler-refs.md 1 KB
• references/rules/advanced-use-latest.md 1 KB
• references/rules/async-api-routes.md 1 KB
• references/rules/async-defer-await.md 2 KB
• references/rules/async-dependencies.md 1 KB
• references/rules/async-parallel.md 1 KB
• references/rules/async-suspense-boundaries.md 2 KB
• references/rules/bundle-barrel-imports.md 2 KB
• references/rules/bundle-conditional.md 1 KB
• references/rules/bundle-defer-third-party.md 1 KB
• references/rules/bundle-dynamic-imports.md 1 KB
• references/rules/bundle-preload.md 1 KB
• references/rules/client-event-listeners.md 2 KB
• references/rules/client-swr-dedup.md 1 KB
• references/rules/js-batch-dom-css.md 2 KB
• references/rules/js-cache-function-results.md 2 KB
• references/rules/js-cache-property-access.md 1 KB
• references/rules/js-cache-storage.md 2 KB
• references/rules/js-combine-iterations.md 1 KB
• references/rules/js-early-exit.md 1 KB
• references/rules/js-hoist-regexp.md 1 KB
• references/rules/js-index-maps.md 1 KB
• references/rules/js-length-check-first.md 2 KB
• references/rules/js-min-max-loop.md 2 KB
• references/rules/js-set-map-lookups.md 1 KB
• references/rules/js-tosorted-immutable.md 2 KB
• references/rules/rendering-activity.md 1 KB
• references/rules/rendering-animate-svg-wrapper.md 1 KB
• references/rules/rendering-conditional-render.md 1 KB
• references/rules/rendering-content-visibility.md 1 KB
• references/rules/rendering-hoist-jsx.md 1 KB
• references/rules/rendering-hydration-no-flicker.md 2 KB
• references/rules/rendering-svg-precision.md 1 KB
• references/rules/rerender-defer-reads.md 1 KB
• references/rules/rerender-dependencies.md 1 KB
• references/rules/rerender-derived-state.md 1 KB
• references/rules/rerender-lazy-state-init.md 2 KB
• references/rules/rerender-memo.md 1 KB
• references/rules/rerender-transitions.md 1 KB
• references/rules/server-cache-lru.md 1 KB
• references/rules/server-cache-react.md 1 KB
• references/rules/server-parallel-fetching.md 1 KB
• references/rules/server-serialization.md 1 KB