React Best Practices Skill

Purpose and Scope

The bundled React best-practices skill is an agent-facing knowledge package for applying Vercel Engineering guidance to React and Next.js performance work. In OpenWiki, skills live under the agent assets tree and can be used by an AI assistant when the task involves writing, reviewing, or refactoring application code. This particular skill is optimized for automated code generation and review: it packages a performance taxonomy, individual rule files, examples, impact levels, metadata, and generated evaluation material into a structure that an agent can consume consistently.

Sources: .agents/skills/vercel-react-best-practices/README.md, .agents/skills/vercel-react-best-practices/SKILL.md, .agents/skills/vercel-react-best-practices/metadata.json

The reader problem this page solves is practical: when you want to add a new React performance guideline, audit an existing rule, or understand what the generated skill is supposed to contain, you need to know which files are source files, which files are generated outputs, and which naming conventions drive categorization. The skill README describes the repository as a structured system for creating and maintaining React Best Practices optimized for agents and LLMs, while the skill manifest explains when the guidance should be invoked during React and Next.js work.

The skill is not just a prose checklist. It is organized as a maintainable rule corpus. Human authors edit individual markdown rule files, section metadata, and document metadata. Build tooling, as declared by the README workflow, compiles those rules into generated outputs such as AGENTS.md and test-cases.json. That separation matters because maintainers should update source rules and regenerate outputs rather than hand-editing compiled artifacts.

Relevant Source Files

• .agents/skills/vercel-react-best-practices/README.md - Describes the skill repository layout, setup commands, generated outputs, naming conventions, impact levels, and contribution workflow.
• .agents/skills/vercel-react-best-practices/SKILL.md - Defines the skill manifest, activation description, license metadata, category priority table, and quick-reference rule catalog.
• .agents/skills/vercel-react-best-practices/metadata.json - Provides versioned document metadata, organization, abstract, and external reference links for the performance guide.
• .agents/skills/vercel-react-best-practices/rules/_sections.md - Defines the eight rule sections, their ordering, filename prefixes, impact levels, and category descriptions.
• .agents/skills/vercel-react-best-practices/rules/_template.md - Provides the required frontmatter and markdown structure for adding an individual rule file.

Core Primitives

The main primitive is a rule: one focused performance recommendation with frontmatter, a title, an explanation, incorrect and correct examples, and an optional reference. Rule files use markdown with YAML-style frontmatter. The template requires fields for title, impact, optional impactDescription, and tags, then asks authors to explain why the rule matters and to provide bad and good TypeScript examples. This shape is important for agent use because it gives the model both policy and concrete transformation examples.

Sources: .agents/skills/vercel-react-best-practices/rules/_template.md

The second primitive is a section. Sections group rules by performance area and are inferred from filename prefixes rather than maintained by manually assigning rule numbers. The section metadata file defines eight ordered sections: Eliminating Waterfalls, Bundle Size Optimization, Server-Side Performance, Client-Side Data Fetching, Re-render Optimization, Rendering Performance, JavaScript Performance, and Advanced Patterns. Each section has a prefix such as async, bundle, server, client, rerender, rendering, js, or advanced, and each prefix maps new rule files into the appropriate category.

Sources: .agents/skills/vercel-react-best-practices/rules/_sections.md

The third primitive is impact. Impact levels communicate expected priority to both humans and agents. The README lists CRITICAL, HIGH, MEDIUM-HIGH, MEDIUM, LOW-MEDIUM, and LOW, with descriptions ranging from major performance gains to incremental improvements. The section file uses those priorities to make waterfalls and bundle size the highest-impact areas, server-side performance high impact, and advanced patterns lower priority. This ordering helps an assistant prefer large structural wins before small optimizations.

Sources: .agents/skills/vercel-react-best-practices/README.md, .agents/skills/vercel-react-best-practices/rules/_sections.md

The fourth primitive is the skill manifest. SKILL.md supplies the name vercel-react-best-practices, MIT license, author and version metadata, and a description that tells an agent when to apply the package. The described triggers include React components, Next.js pages, data fetching, bundle optimization, and performance improvements. That makes the skill broader than a single lint rule: it is intended for design, implementation, review, and refactoring tasks across React and Next.js applications.

Sources: .agents/skills/vercel-react-best-practices/SKILL.md

Rule Taxonomy and Generated Outputs

The taxonomy is deliberately performance-first. Eliminating Waterfalls is marked CRITICAL because sequential awaits add network latency and often dominate user-perceived speed. Bundle Size Optimization is also CRITICAL because reducing initial JavaScript improves Time to Interactive and Largest Contentful Paint. Server-Side Performance focuses on server rendering and data-fetching response time, while client-side data fetching emphasizes deduplication and efficient request patterns. Later categories address rerenders, browser rendering work, JavaScript hot paths, and advanced cases that require careful implementation.

The SKILL quick reference expands those categories into concrete rule identifiers. Examples include async-parallel for independent Promise.all work, async-suspense-boundaries for streaming content, bundle-barrel-imports for avoiding broad imports, bundle-dynamic-imports for heavy components, server-cache-react for per-request deduplication, client-swr-dedup for client request deduplication, and rerender-memo for isolating expensive work. The source evidence shows the catalog as an evolving generated guide, so maintainers should treat rule files and section metadata as the stable editing surfaces.

Sources: .agents/skills/vercel-react-best-practices/SKILL.md, .agents/skills/vercel-react-best-practices/rules/_sections.md

Generated outputs are part of the workflow but not the files authors should normally edit. The README identifies AGENTS.md as the compiled output and test-cases.json as generated LLM-evaluation material. It also declares extract-tests as the command for extracting test cases. This is useful for agent-quality maintenance: a rule should include enough clear examples and explanation that it can be compiled for model consumption and converted into cases that check whether an LLM applies the rule correctly.

Sources: .agents/skills/vercel-react-best-practices/README.md

Authoring Workflow

To create a new rule, start from rules/_template.md rather than improvising a shape. Copy it to a non-underscore filename such as rules/async-parallel.md or rules/bundle-dynamic-imports.md. Files beginning with an underscore are special support files and are excluded from the build. Normal rule files use the area-description naming pattern, where the area prefix selects the section. Because IDs are auto-generated during build and rules are sorted alphabetically by title inside each section, authors do not need to manage numbering manually.

After creating the file, choose the correct prefix from the documented set: async for Eliminating Waterfalls, bundle for Bundle Size Optimization, server for Server-Side Performance, client for Client-Side Data Fetching, rerender for Re-render Optimization, rendering for Rendering Performance, js for JavaScript Performance, or advanced for Advanced Patterns. Then fill in frontmatter with a clear title, an impact value, optional impact description, and tags. The body should explain the performance implication before showing incorrect and correct examples.

Sources: .agents/skills/vercel-react-best-practices/README.md, .agents/skills/vercel-react-best-practices/rules/_template.md

A useful rule should be explicit enough for an agent to act on. The template asks for an incorrect example and a correct example in TypeScript, each with a short description. That means the rule should not only state a preference such as prefer direct imports or parallelize independent requests; it should demonstrate the code shape to avoid, the replacement pattern, and the reason the replacement improves runtime behavior. References should point to authoritative documentation or supporting material when available.

Once the rule is authored, run the declared maintenance commands. The README workflow starts with pnpm install, then uses pnpm build to compile rules, pnpm validate to validate rule files, and pnpm extract-tests to generate evaluation cases. The dev command is documented as build plus validate. In normal contribution flow, regenerate AGENTS.md and test-cases.json after changing rules so the compiled agent-facing artifacts stay synchronized with the source markdown.

pnpm install
pnpm build
pnpm validate
pnpm extract-tests

Sources: .agents/skills/vercel-react-best-practices/README.md

Compact Reference

Validation and Next Steps

When reviewing a change to this skill, check the source rule first, then the generated artifacts. Confirm that the filename prefix matches the intended section, that the frontmatter impact uses a documented impact level, that tags are present, and that the body includes both incorrect and correct examples. Then run the build and validation commands from the README. If the rule should support LLM evaluation, make sure its examples are concrete enough for extraction into test cases.

For broader OpenWiki work, read the agent and instruction pages next. The React skill is one example of how this repository packages agent-consumable guidance, while the indexing and subagent documentation explains how OpenWiki itself uses structured instructions to generate source-grounded wiki pages. If you are adding new skill content, stay close to the template and section metadata; if you are changing how skills are loaded or invoked, follow the agent architecture documentation instead.