| name | react-best-practices |
| description | Use when writing, reviewing, or refactoring React code — components, hooks, data fetching, bundle optimization, re-render performance, or rendering throughput. Skip for non-React TypeScript, backend, or framework configuration. |
React Best Practices
Performance optimization guide for React. Rules are split across 6 categories by impact, each backed by a file in rules/ with full explanation and before/after examples.
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 | Advanced Patterns | LOW | advanced- |
Quick Reference
1. Eliminating Waterfalls (CRITICAL)
async-defer-await - Move await into branches where actually usedasync-parallel - Use Promise.all() for independent operations
2. Bundle Size Optimization (CRITICAL)
bundle-dynamic-imports - Use next/dynamic for heavy componentsbundle-defer-third-party - Load analytics/logging after hydrationbundle-conditional - Load modules only when feature is activatedbundle-preload - Preload on hover/focus for perceived speed
3. Client-Side Data Fetching (MEDIUM-HIGH)
client-event-listeners - Deduplicate global event listenersclient-passive-event-listeners - Use passive listeners for scroll/touch
4. Re-render Optimization (MEDIUM)
rerender-defer-reads - Don't subscribe to state only used in callbacksrerender-memo - Extract expensive work into memoized componentsrerender-dependencies - Use primitive dependencies in effectsrerender-derived-state - Subscribe to derived booleans, not raw valuesrerender-functional-setstate - Use functional setState for stable callbacksrerender-lazy-state-init - Pass function to useState for expensive valuesrerender-transitions - Use startTransition for non-urgent updates
5. Rendering Performance (MEDIUM)
rendering-animate-svg-wrapper - Animate div wrapper, not SVG elementrendering-content-visibility - Use content-visibility for long listsrendering-hoist-jsx - Extract static JSX outside componentsrendering-svg-precision - Reduce SVG coordinate precisionrendering-hydration-no-flicker - Use inline script for client-only datarendering-activity - Use Activity component for show/hiderendering-conditional-render - Use ternary, not && for conditionals
6. Advanced Patterns (LOW)
advanced-event-handler-refs - Store event handlers in refs
How to Use
Read individual rule files for detailed explanations and code examples:
rules/async-parallel.md
rules/_sections.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
