The paper introduces react-best-practices, a structured repository designed to encapsulate over ten years of React and Next.js optimization knowledge, specifically tailored for consumption by AI agents and Large Language Models (LLMs). It addresses the common pitfall of reactive performance optimization, where teams chase symptoms post-release, leading to inefficient and often misdirected efforts. The authors identify three pervasive root causes for performance degradation: accidental sequentialization of asynchronous operations (async waterfalls), continuously growing client-side bundle sizes, and excessive component re-renders. These are highlighted as non-micro-optimizations that directly translate into user-perceived waiting time, jank, and recurring operational costs.

The core methodology of react-best-practices is predicated on a hierarchical ordering of optimization efforts, moving from the highest impact, foundational issues down to incremental improvements. This approach counters the tendency to optimize "too low in the stack" prematurely, such as focusing on useMemo optimizations when significant latency is introduced by request waterfalls or large JavaScript payloads. The framework posits that performance work compounds; thus, a small regression today becomes a perpetual tax on every user session until it is addressed.

The established prioritization framework dictates the following sequence of optimization categories, ordered by their typical real-world impact:

1. Eliminating Async Waterfalls (CRITICAL): This involves identifying and refactoring sequential asynchronous operations that do not have interdependencies, allowing them to execute in parallel. For instance, if an operation $O_1$ and $O_2$ are independent, executing them sequentially leads to a total time of $T(O_1) + T(O_2)$, whereas parallel execution (e.g., using Promise.all or by reordering conditional logic) can reduce it to $\max(T(O_1), T(O_2))$. The provided example illustrates moving an await fetchUserData call inside a conditional block, ensuring it's only executed when userData is genuinely required, thus preventing an unnecessary network latency.
2. Bundle Size Optimization (CRITICAL): Focuses on reducing the size of client-side JavaScript bundles, which directly impacts initial load times and parse/execute costs.
3. Server-side Performance: Optimizations pertaining to the backend processing and response times.
4. Client-side Data Fetching: Strategies for efficient data retrieval on the client, beyond just waterfall elimination.
5. Re-render Optimization: Techniques to minimize unnecessary component re-renders in React applications.
6. Rendering Performance: General improvements related to the browser's rendering pipeline.
7. Advanced Patterns: More nuanced optimization techniques.
8. JavaScript Performance: General JavaScript code efficiency.

The repository comprises over 40 rules categorized across these eight areas. Each rule is assigned an impact rating (from CRITICAL to LOW) to guide prioritization and includes concrete code examples demonstrating incorrect implementations ("what breaks") and their correct, optimized counterparts ("how to fix it").

A significant aspect of react-best-practices is its explicit design for AI agents. The individual rule files are compiled into a single document, AGENTS.md, enabling AI agents to query and reference these patterns during code reviews, refactoring suggestions, or automated code modifications. Furthermore, these best practices are packaged as "Agent Skills" compatible with various coding agents (e.g., Opencode, Codex, Claude Code, Cursor), allowing them to automatically detect and suggest fixes for patterns like cascading useEffect calls or heavy client-side imports. The underlying practices are not theoretical; they are derived from extensive real-world performance work on production codebases, exemplified by optimizations such as combining multiple loop iterations into a single pass, parallelizing independent API calls, and fine-tuning aesthetic details like font fallbacks.