React Best Practices
Comprehensive performance optimization guide for React applications. Contains 47 rules across 7 categories, prioritized by impact to guide automated refactoring and code generation. Next.js-specific rules have been removed for this project (Electron + Vite + React 19). Originally from vercel-labs/agent-skills (MIT).
When to Apply
Reference these guidelines when:
- •Writing new React components
- •Implementing data fetching (client-side)
- •Reviewing code for performance issues
- •Refactoring existing React code
- •Optimizing bundle size or load times
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Eliminating Waterfalls | CRITICAL | async- |
| 2 | Bundle Size Optimization | CRITICAL | bundle- |
| 3 | Client-Side Data Fetching | MEDIUM-HIGH | client- |
| 4 | Re-render Optimization | MEDIUM | rerender- |
| 5 | Rendering Performance | MEDIUM | rendering- |
| 6 | JavaScript Performance | LOW-MEDIUM | js- |
| 7 | Advanced Patterns | LOW | advanced- |
Quick Reference
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
2. Bundle Size Optimization (CRITICAL)
- •
bundle-barrel-imports- Import directly, avoid barrel files - •
bundle-conditional- Load modules only when feature is activated - •
bundle-preload- Preload on hover/focus for perceived speed
3. Client-Side Data Fetching (MEDIUM-HIGH)
- •
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
4. 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-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
5. 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-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
6. 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
7. Advanced Patterns (LOW)
- •
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
Read individual rule files for detailed explanations and code examples:
code
rules/async-parallel.md rules/bundle-barrel-imports.md
Each rule file contains:
- •Brief explanation of why it matters
- •Incorrect code example with explanation
- •Correct code example with explanation
- •Additional context and references
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md