Vercel, the cloud platform behind Next.js, has released react-best-practices, an open-source repository containing over 40 performance optimization rules for React and Next.js applications. The framework, which encapsulates over a decade of engineering knowledge from Vercel’s production codebases, is structured specifically for consumption by AI coding agents and LLMs, though the team notes it is equally valuable for human developers.
The repository organises its rules across eight categories, each prioritised by impact level from CRITICAL to LOW. The two highest-priority categories focus on eliminating async waterfalls and reducing bundle size, which Vercel’s engineering team identified as the most common root causes of performance issues across production applications. Further categories cover server-side performance, client-side data fetching, re-render optimisation, rendering performance, advanced patterns, and JavaScript micro-optimisations.
Each rule includes code examples demonstrating both incorrect and correct patterns.
The individual rule files compile into a single AGENTS.md document, designed to be queried by AI agents when reviewing or refactoring code. The framework is distributed as part of Vercel’s broader Agent Skills ecosystem, an open format for giving agents new capabilities. Developers can install the skill into tools such as Claude Code, Cursor, Codex, and OpenCode using a single command: npx skills add vercel-labs/agent-skills.
The release has generated mixed interest from the developer community. On the r/vibecoding subreddit, one commenter saw its usefulness for vibe coding success:
Definitely looks useful, I was surprised to see how large the prompts/context tokens were for vibe coding agents like v0 and Lovable. Context engineering is definitely the biggest factor for vibe coding success
Elsewhere, some users are worried about the security aspects:
Imagine a supply chain attack on a skill description which is fed to an AI agent. Interesting times.
In a separate reddit post, one commenter suggested that they might be solving the wrong problem:
This feels like the right direction but i wonder if we’re solving the wrong problem. Codified best practices are great but most AI coding failures I see aren’t from missing React optimization rules – they’re from agents not understanding the actual business logic or making assumptions about what the user wants.
The framework occupies a different space to existing tools such as eslint-plugin-react and eslint-plugin-react-hooks, which enforce syntactic rules and hook usage patterns at the linter level. Vercel’s offering focuses on higher-level architectural decisions, such as request waterfalls and bundle composition, that linting tools typically do not cover. The recently released React Compiler v1.0 also complements the framework, automatically handling memoization optimisations that several of the rules address manually.
At time of writing the GitHub repo as over 21k stars and over 150k weekly installs.
For teams looking to adopt the framework in existing projects, the repository is structured so that each rule can be reviewed and applied independently. Individual rule files are located in the rules directory and include explanations of why each pattern matters alongside before-and-after code examples, making incremental adoption straightforward.
Vercel’s react-best-practices is open source under the MIT licence. The repository and full AGENTS.md compiled document are available on GitHub.
