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:

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: e 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