React Best Practices
Attribution: This skill is forked from vercel-labs/agent-skills. All documentation and references are included locally in this repository - no network access required.
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