Vercel React Best Practices

tl;dr: the rules file half of vercel-labs/agent-skills for React performance — 70 rules across 8 priority bands, walked by impact. The other half of the repo is composition-patterns (component API shape); the mobile sibling is react-native-skills. Load this when the complaint is render speed, bundle size, or a waterfall.

What it actually does

SKILL.md (version 1.0.0, 2026-09-09) is a prioritised index, not a wall of text. The agent reads the matching rules/<prefix>-*.md file when the user signals a perf job:

The CRITICAL band is what most agents skip and most apps need: async-parallel (Promise.all for independent fetches), async-suspense-boundaries (stream with Suspense instead of awaiting in the parent), bundle-barrel-imports (no barrel re-exports — they pull the whole tree), bundle-dynamic-imports (next/dynamic for heavy components), bundle-defer-third-party (analytics after hydration, not before).

HIGH band leans server: server-cache-react (React.cache for per-request dedup), server-parallel-fetching (restructure components so siblings fetch in parallel, not parents-then-children), server-no-shared-module-state (don’t keep mutable request state in module scope — RSC/SSR will leak between users).

The full compiled guide is AGENTS.md at the repo root. Rule files are linked, not pasted, so the agent walks them on demand.

When the agent should load it

The description field enumerates the trigger phrases:

• “Writing, reviewing, or refactoring React / Next.js code”
• “Implementing data fetching (client or server-side)”
• “Optimizing bundle size or load times”
• Tasks involving React components, Next.js pages, data fetching, or performance improvements

If the user says “this page is slow” or “the bundle is huge”, this is the right skill. If they say “review my <Button> for boolean prop sprawl”, load composition-patterns instead — that’s the architecture half of the same repo. If they’re building for iOS/Android, load react-native-skills.

Install

# installs the whole vercel-labs/agent-skills pack (includes this skill)
npx skills add vercel-labs/agent-skills

The npx skills add invocation is what the upstream README documents. If your host does not speak the Agent Skills loader (or you want just this one skill), clone the repo and point the agent at the file:

git clone https://github.com/vercel-labs/agent-skills
# Claude Code / Cursor pick up SKILL.md from:
#   ~/.claude/skills/react-best-practices/SKILL.md
#   .claude/skills/react-best-practices/SKILL.md
# or any path the host's skill loader watches

The published GitHub release for this skill ships as a .skill artifact (zip with SKILL.md + rules/). Unzip into the same path if your host expects that layout.

Gotchas

• Not the architecture skill. react-best-practices is for render speed, waterfalls, bundle size. composition-patterns is for component API shape. Agents that conflate the two over-apply rules: e.g., adding React.memo to a component with a stable callback instead of fixing a waterfall.
• 70 rules is a hint, not a checklist. The priority table exists so the agent reads the CRITICAL band first. Agents that load all 70 at once waste tokens and lose the ranking. Read rules/<prefix>-*.md on demand.
• Server rules are RSC-specific. The server- prefix assumes React Server Components. If the project is a Vite SPA or a Pages-Router app, the server-* rules misfire — the agent should stop at the client- band.
• React Compiler changes some rerender- advice. rerender-memo and friends are largely unnecessary once the React Compiler is enabled and stable. The skill does not gate on compiler presence — agents that don’t check package.json for babel-plugin-react-compiler will over-memo.
• AGENTS.md is the compiled source of truth. If SKILL.md and rules/*.md ever drift, AGENTS.md is the one to trust. It is not auto-generated at install time.
• sandbox_test.verdict: untested — we read SKILL.md and the README; we did not run an agent through the rule checklist.

Related: Vercel Composition Patterns — same repo, perf vs architecture pair; Vercel React Native Skills — mobile sibling, same author and rule format; Refactoring UI Audit — pair the visual audit with this perf skill when the page renders fast but still looks generic; UI Skills catalog — broader routing index for UI jobs.