Introducing: React Best Practices

We've encapsulated 10+ years of React and Next.js optimization knowledge into react-best-practices, a structured repository optimized for AI agents and LLMs.

V

VercelVercel

·January 14, 2026

React performance: start with the fixes that actually matter

Most React performance work is reactive. A release ships, the app feels sluggish, and teams start chasing symptoms. That approach is costly and often targets the wrong part of the stack. After more than a decade of working across production codebases at Vercel, the same root causes keep showing up:

Async work that accidentally becomes sequential
Client bundles that keep growing
Components re-rendering more than necessary

These aren't micro-optimizations. They surface as waiting time, jank, and recurring costs on every user session. To make them easier to spot and fix, Vercel has published react-best-practices, a structured repository designed for both human developers and AI agents.

Ordering fixes by real-world impact

Performance work often fails because it starts too far down the stack. If a request waterfall adds 600ms of waiting time, well-optimized useMemo calls won't save you. If you're shipping 300KB of extra JavaScript per page, shaving microseconds off a loop is pointless.

Performance issues also compound. A small regression shipped today becomes a tax on every session until someone pays down the debt. That's why the framework prioritizes the two fixes that typically move metrics first:

Eliminating waterfalls
Reducing bundle size

From there, the framework works through server-side performance, client-side fetching, and re-render optimization. In total, it contains 40+ rules across 8 categories, each with an impact rating from CRITICAL to LOW so teams can focus on the highest-leverage changes first.

Inside the rule set

The eight categories cover the full span of React performance work: eliminating async waterfalls, bundle size optimization, server-side performance, client-side data fetching, re-render optimization, rendering performance, advanced patterns, and JavaScript performance. Every rule includes an impact rating plus code examples showing the broken pattern and the fix.

One common example is dynamic imports that block both branches of a conditional. The incorrect version prevents unused code from being split:

async function handleRequest(userId: string, skipProcessing: boolean) {
  const userData = await fetchUserData(userId)
  if (skipProcessing) {
    // Returns immediately but still waited for userData
    return { skipped: true }
  }
  // Only this branch uses userData
  return processUserData(userData)
}

The correct version only fetches the module when it's actually needed:

async function handleRequest(
  userId: string,
  skipProcessing: boolean
) {
  if (skipProcessing) {
    return { skipped: true }
  }
  const userData = await fetchUserData(userId)
  return processUserData(userData)
}

Individual rule files are compiled into AGENTS.md, a single document that coding agents can query during reviews or refactors. That structure lets teams apply consistent decisions across large codebases, whether the work is done by humans or by AI.

Where the practices come from

These rules aren't theoretical. They're drawn directly from production performance work. The repository includes concrete examples like these:

Combining loop iterations: a chat page was scanning the same list of messages eight separate times. Merging those scans into a single pass made a measurable difference with thousands of messages.
Parallelizing awaits: an API was running independent database calls sequentially. Running them concurrently cut total wait time in half.
Lazy State Initialization: a component was parsing a JSON config from localStorage on every render when it only needed the value once. Moving the parse into a useState(() => JSON.parse(...)) callback eliminated the wasted work.

Bringing best practices into your coding agent

The same practices are packaged as Agent Skills that can be installed into Opencode, Codex, Claude Code, Cursor, and other coding agents. When an agent spots cascading useEffect calls or heavy client-side imports, it can reference these patterns and suggest targeted fixes instead of guesswork.