This is Vercel's performance guide for React and Next.js, written for an AI agent to follow. It holds 70 rules, each with a wrong and a right code example, sorted by how much they matter: request waterfalls and bundle size first, micro-optimisations last. Once it's installed, your agent checks its React code against the rules as it writes and reviews.
What it does
The rules sit in eight groups, in priority order:
| Priority | Group | Example rule |
|---|---|---|
| Critical | Waterfalls | Start independent requests together with Promise.all() |
| Critical | Bundle size | Import from the file, not the barrel index.ts |
| High | Server | Deduplicate per-request work with React.cache() |
| Medium-high | Client data | Share one request across components with SWR |
| Medium | Re-renders | Derive values during render instead of syncing them in an effect |
| Medium | Rendering | Use a ternary, not &&, when the condition can be 0 |
| Low-medium | JavaScript | Build a Map instead of calling .find() in a loop |
| Low | Advanced | Keep useEffectEvent results out of dependency arrays |
SKILL.md is the index. Each rule is a short file under rules/ that the
agent opens when a rule applies, so most of the guide stays out of its context
until it's needed.
The skill describes its own purpose like this:
Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 70 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
From SKILL.md by Vercel, MIT.
An example
A page component awaits the user, then the user's posts, then the site config,
one after another. Ask the agent to "make this page load faster" and, with the
skill loaded, it names the rule it's applying (async-parallel), starts the
three requests together, and wraps the slow part in a Suspense boundary
(async-suspense-boundaries) so the rest of the page can render first. The
rule names make it easy to look up why a change was made.
When to use it, and when not to
Use it on any React or Next.js project, and especially when you ask your agent to review a component or speed up a slow page. It's also a good way to learn: read the rule file behind each change your agent makes.
It's less useful outside React. It's a performance guide first: a few rules touch security, like authenticating server actions, but it won't catch accessibility problems or plain bugs, and it doesn't replace a security review.
What we checked
We read every file in the folder at the commit linked above: SKILL.md,
README.md, metadata.json, the 72 files under rules/ (70 rules, a
template and a section list) and AGENTS.md, which the repo generates from
those rules. There are no scripts and no allowed-tools, and nothing tells the
agent to fetch anything. The links in the rules point at React, Next.js, MDN
and library docs, for you to read. The repo licence is MIT, and the skill says
so in its frontmatter.
One thing to know: this skill's name (vercel-react-best-practices) differs
from its folder name, which is why the install commands above use the longer
name. Our full checklist is in the
guide to checking a skill before you install it.
For the look of the page rather than its speed, see Anthropic's frontend design skill.