Foreword¶

When using AI coding tools like Cursor, Claude Code, or Codex to write React / Next.js applications, components and pages often get up and running quickly. However, common production issues still persist: APIs waiting in serial one after another, client-side bundles growing larger and larger, and full-page re-renders triggered by irrelevant state changes. Performance issues are usually addressed “after the fact”: after noticing a slowdown after deployment, developers will then go back to add useMemo or split bundles, which is costly and easy to get wrong.

The Vercel Engineering team has compiled years of production pitfall experiences into a rulebase for AI Agents, packaged as an Agent Skill: react-best-practices (officially named vercel-react-best-practices). After installation, the Agent will apply these rules based on impact priority when writing components, fetching data, or performing refactoring, instead of getting stuck on micro-optimizations upfront.

This article introduces what it is, how the rules are categorized, how to install and enable it, and how to use it in daily development, based on information verified from the official repository and Vercel blog.

What is it¶

vercel-react-best-practices is an official Agent Skill maintained by Vercel, hosted in the skills/react-best-practices/ directory of the vercel-labs/agent-skills repository. It is licensed under MIT, with author: vercel and version: "1.0.0" noted in SKILL.md.

One-sentence positioning: A performance optimization guide for React / Next.js, specially formatted to be readable and executable by AI Agents, used to align on a unified set of high-performance patterns during coding, review, and refactoring.

As of the current SKILL.md, the rule set includes 70 rules across 8 categories, sorted from highest to lowest impact, to guide automated refactoring and code generation. It is important to note: As of January 2026, the Vercel official blog and repository README still state “40+ rules”; based on the primary source SKILL.md, the number of rules has been expanded to 70. The early “40+” publicity can be understood as the scale at launch, and does not affect the core design of “organized by impact priority”.

Its core problem-solving focus is straightforward: shift performance work from “symptom-driven” to “fixing the right areas by priority” — first eliminate request waterfalls, then reduce bundle size, then address server-side and client-side details, and finally move on to micro-optimizations.

Core Features and Highlights¶

1. Eight categories of rules sorted by impact¶

The official team has divided the rules into 8 categories, with clear priority levels and prefixes, making it easy for Agents to locate detailed rules by filename:

The Vercel blog emphasizes that most performance optimization efforts fail because developers start from the lowest level of the stack. If a request waterfall adds hundreds of milliseconds of delay, tweaking useMemo will not save the first screen load time; if each page adds an extra 300KB of JS, saving a few microseconds in a loop will barely be noticeable. Therefore, the CRITICAL level first focuses on async waterfall and bundle size issues.

2. Each rule includes “bad example / good example”¶

The detailed rule files are stored in the rules/ directory under the Skill folder (for example, rules/async-parallel.md). Each rule typically includes: why it matters, incorrect usage, correct usage, and supplementary notes. All rules are also aggregated into AGENTS.md for Agents to reference in one go.

Take the official example async-parallel (using Promise.all for independent asynchronous operations) as an example:

Incorrect (serial, three round trips):

const user = await fetchUser()
const posts = await fetchPosts()
const comments = await fetchComments()

Correct (parallel, one round trip):

const [user, posts, comments] = await Promise.all([
  fetchUser(),
  fetchPosts(),
  fetchComments()
])

Another common waterfall pattern mentioned in the blog is data that is never used in a branch being awaited before the branch condition is checked — the correct approach is to move the await inside the branch where it is actually needed (corresponding to rules like async-defer-await).

3. Trigger scenarios are documented in the Skill description¶

The description field in SKILL.md specifies: This Skill should be used when writing, reviewing, or refactoring React / Next.js code involving components, pages, data fetching, bundle optimization, or performance improvements. After installation, the Agent will automatically reference these guidelines for relevant tasks.

4. Source material is production-tested, not theoretical¶

The Vercel blog states that the rules are derived from over a decade of React / Next.js optimization experience and performance work in real production codebases (such as merging multiple message list scans into a single traversal, parallelizing independent await calls, using lazy initialization to avoid JSON.parseing localStorage on every render, etc.). The Skill codifies these experiences into a checklist that Agents can repeatedly execute against.

Installation and Activation¶

This Skill follows the universal Agent Skills format and can be installed using the official Skills CLI. Vercel documentation notes that Skills work with over 18 AI Agents including Claude Code, GitHub Copilot, Cursor, and Cline.

Install only this single Skill (Recommended)¶

The installation command provided in the official documentation and skills.sh is:

npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices

It can also be written using the full repository URL:

npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-best-practices

Note: When installing, the --skill parameter must use the official name vercel-react-best-practices (the repository renamed the name from react-best-practices to this name in June 2026), while the directory name remains skills/react-best-practices/.

Install the entire agent-skills repository¶

If you wish to install other Skills from the same repository at the same time (such as web-design-guidelines, composition-patterns, etc.):

npx skills add vercel-labs/agent-skills

The CLI will parse the repository, detect all included Skills, detect the coding Agents already installed on your machine, and guide you through selecting the installation scope and method.

Project-level vs Global installation¶

• The default installation targets the current project (ideal for committing to the repository and sharing across your team).
• Add the -g flag to install at the user level for cross-project availability:

npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices -g

Environment requirements: The Skills CLI requires Node.js 18+, and can be run directly with npx without prior global installation of the CLI.

No additional configuration is generally required after installation: When relevant tasks arise, the Agent will automatically reference the rules as specified in the Skill.

Typical Usage Examples¶

The official README provides straightforward usage instructions. After installation, you can trigger it using natural language in tools like Cursor / Claude Code / Codex, for example:

Review this React component for performance issues

Help me optimize this Next.js page

For more specific requests, you can call out the CRITICAL level issues:

Review this page according to vercel-react-best-practices:
1. Check for async request waterfalls (serial instead of parallel, premature await calls)
2. Check for barrel imports / heavy client-side dependencies causing bundle bloat
3. Provide the corresponding rule prefixes (such as async-, bundle-) and fixes

The Agent will reference the detailed rules in the rules/ directory or AGENTS.md. You can also open individual rule files to learn directly, for example:

rules/async-parallel.md
rules/bundle-barrel-imports.md
rules/server-cache-react.md

There are several high-priority rule names from the CRITICAL / HIGH categories worth remembering first (extracted from the quick reference in SKILL.md):
- async-parallel: Use Promise.all for independent operations
- async-defer-await: Only await inside branches where the data is actually used
- async-suspense-boundaries: Use Suspense for streaming output
- bundle-barrel-imports: Avoid barrel files, import directly on demand
- bundle-dynamic-imports: Use next/dynamic for heavy components
- server-cache-react: Use React.cache() for request-level deduplication
- server-parallel-fetching: Adjust component structure to fetch data in parallel

Applicable Scenarios and Notes¶

Who should use it, and when¶

• Daily development of React components and Next.js App Router pages using AI tools
• Conducting dedicated performance reviews during Code Review (waterfalls, bundle size, RSC serialization, re-renders)
• Refactoring existing pages: Prioritize CRITICAL → HIGH level issues first, then address MEDIUM / LOW level items
• Teams that want “humans and Agents to use the same performance decision framework” to reduce style drift

Usage notes¶

1. Start with high-priority optimizations, then move to micro-optimizations. The rules are already sorted by impact; first eliminate waterfalls and reduce bundle waste, then tweak js-* micro-optimizations, otherwise the benefits will be minimal.
2. Use the current SKILL.md as the authoritative source for rule count. When there is a discrepancy between the blog/README’s “40+” and the SKILL.md’s “70”, refer to the Skill metadata in the repository.
3. Do not use the wrong name for installation. It is often referred to as react-best-practices publicly, but the --skill parameter for the CLI must use vercel-react-best-practices.
4. This is a guide, not runtime monitoring. The Skill will not collect real-user monitoring (RUM) data for you; after making changes, it is still recommended to validate using real metrics and build analysis tools.
5. Some rules depend on newer Next.js / React features (such as after(), Activity, useEffectEvent, etc.). If your project uses an older version, the Agent may suggest syntax that is not compatible with your current stack, and you will need to manually adjust based on your dependency versions.

Summary¶

react-best-practices (vercel-react-best-practices) packages Vercel Engineering’s React / Next.js performance experience into an Agent Skill sorted by impact: first eliminate waterfalls and bundle waste, then cover server-side, client-side data, re-renders, and advanced patterns. For frontend teams that already offload a large amount of boilerplate code to AI, it acts as a “quality gatekeeper” — ensuring that generated and refactored code defaults to align with a unified set of high-performance patterns.

Official links:
- Skill directory: https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices
- skills.sh page: https://skills.sh/vercel-labs/agent-skills/react-best-practices
- Introductory blog post: https://vercel.com/blog/introducing-react-best-practices
- Agent Skills documentation: https://vercel.com/docs/agent-resources/skills