Introducing React Best Practices: A Structured Repo for AI Agents

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.

React performance work is usually, well, reactive. A release goes out, the app feels slower, and the team starts chasing symptoms. That’s expensive, and it’s easy to optimize the wrong thing.

We’ve seen the same root causes across production codebases for more than a decade:

Async work that accidentally becomes sequential

Large client bundles that grow over time

Components that re-render more than they need to

The “why” here is simple: these aren’t micro-optimizations. They show up as waiting time, jank, and repeat costs that hit every user session.

So, we put together this React best practices framework to make those problems easier to spot and faster to fix.

Link to headingThe core idea: ordering

Most performance work fails because it starts too low in the stack.

If a request waterfall adds 600ms of waiting time, it doesn’t matter how optimized your useMemo calls are. If you ship an extra 300KB of JavaScript on every page, shaving a few microseconds off a loop won’t matter.

Performance work also compounds. A small regression you ship today becomes a long-term tax on every session until someone pays down the debt.

So the framework starts with the two fixes that usually move real-world metrics first:

Eliminate waterfalls

Reduce bundle size

Then it moves on to server-side performance, client-side fetching, and re-render optimization.

It includes 40+ rules across 8 categories, ordered by impact, from CRITICAL (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns).‍​‌ ‌ ‌

Link to headingWhat else is inside?

The repository covers eight performance categories:

Eliminating async waterfalls

Bundle size optimization

Server-side performance

Client-side data fetching

Re-render optimization

Rendering performance

Advanced patterns

JavaScript performance

Each rule includes an impact rating (CRITICAL to LOW) to help prioritize fixes, plus code examples showing what breaks and how to fix it.

For example, here’s a common pattern that blocks unused code:

Incorrect (blocks both branches):

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)
}

Correct (only blocks when needed):

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

Individual rule files compile into AGENTS.md, a single document that your agents can query when reviewing code or suggesting optimizations. It’s designed to be followed consistently, including by AI agents doing refactors, so teams can apply the same decisions across a large codebase.

Link to headingHow these practices were collected

These aren’t theoretical. They come from real performance work on production codebases.

A few examples:

Combining loop iterations

A chat page was scanning the same list of messages eight separate times. We combined it into a single pass, which adds up when you have thousands of messages.

Parallelizing awaits

An API was waiting for one database call to finish before starting the next, even though they didn’t depend on each other. Running them at the same time cut the total wait in half.

Lazy State Initialization

A component was parsing a JSON config from localStorage on every render, even though it only needed it once for state initialization. Wrapping the it in a callback (useState(() => JSON.parse(...))) eliminated wasted work.

Link to headingUsing react-best-practices in your coding agent

These best practices are also packaged up as Agent Skills that install into Opencode, Codex, Claude Code, Cursor, and other coding agents. When your agent spots cascading useEffect calls or heavy client-side imports, it can reference these patterns and suggest fixes.

npx skills add vercel-labs/agent-skills

Check out the react-best-practices repository.