vercel-labs/agent-skills

vercel-react-best-practices

Vercel's prioritized guidance for reviewing React and Next.js performance patterns.

View source

Overview

This Skill helps decide where a React or Next.js performance review should start. The pinned version organizes 70 rules into eight categories. Request waterfalls and bundle size carry its highest priority; server work, client data fetching, re-renders, rendering, JavaScript and advanced patterns follow. That order gives an assistant a way to examine costly dependencies and loading work before spending time on smaller local rewrites.

SKILL.md is the entry point rather than the entire reference. Individual files under rules/ explain a pattern with incorrect and corrected examples; AGENTS.md collects the expanded guidance. For example, async-parallel concerns independent operations, while bundle-barrel-imports examines import structure. Open the relevant explanation before applying it to a component. Existing data dependencies, authentication boundaries and framework versions still determine which change is appropriate.

What to prepare

  • The React or Next.js version, the relevant page and component files, and the task you want reviewed.
  • Data-fetching and import code connected to that task; existing bundle or performance diagnostics are useful when available.
  • Behavior that must be preserved, including request dependencies, server/client boundaries and authorization requirements.

What you get

  • Review suggestions tied to specific rules and their stated impact categories.
  • Relevant code patterns and examples from the rule files for evaluating a proposed change.
  • Candidate improvements to verify with the project's own build, behavior checks and performance measurements.

Suggested workflow

  1. Identify the target page or component, its framework version and the behavior or loading problem you want to investigate.
  2. Start with the waterfall and bundle categories, then inspect the categories that match the code under review.
  3. Read the relevant rule file or its expanded AGENTS.md section instead of relying on the one-line index alone.
  4. Check the proposed change against real dependencies, request scope, authorization and supported APIs.
  5. If changing code in your own project, apply a focused change and compare behavior and available diagnostics under the same conditions.

Limits and checks

  • Parallelized operations are actually independent; required data and authorization ordering remains intact.
  • Import or lazy-loading changes fit the component's server/client boundary.
  • Caching does not introduce shared mutable request state or mix data across users.
  • The project supports the React or Next.js APIs used by the selected rule.
  • Tests and measurements support the proposed improvement; a rule label alone is not a measured performance result.

Common questions

Is this only useful for Next.js projects?

The source covers React and Next.js. Component state, re-rendering and JavaScript rules can be relevant to React code, while server actions and other framework-specific patterns need the corresponding environment. Select applicable rules rather than treating the whole list as mandatory.

Should I copy only SKILL.md?

The entry document points to individual rules and the expanded AGENTS.md. Keep the complete Skill package available to the assistant so it can read explanations and examples behind the short index.

Does it provide a performance score for my application?

The package provides guidance and code examples, not a measurement of your application. Use your own build and diagnostic tools to compare a proposed change against the original under consistent conditions.

Install this skill

Use the Skills CLI to add this skill from its verified GitHub source.

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

Source information

Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Vercel React Best Practices

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.

When to Apply

Reference these guidelines when:

  • Writing new React components or Next.js pages
  • Implementing data fetching (client or server-side)
  • Reviewing code for performance issues
  • Refactoring existing React/Next.js code
  • Optimizing bundle size or load times

Rule Categories by Priority

PriorityCategoryImpactPrefix
1Eliminating WaterfallsCRITICALasync-
2Bundle Size OptimizationCRITICALbundle-
3Server-Side PerformanceHIGHserver-
4Client-Side Data FetchingMEDIUM-HIGHclient-
5Re-render OptimizationMEDIUMrerender-
6Rendering PerformanceMEDIUMrendering-
7JavaScript PerformanceLOW-MEDIUMjs-
8Advanced PatternsLOWadvanced-

Quick Reference

1. Eliminating Waterfalls (CRITICAL)

  • async-cheap-condition-before-await - Check cheap sync conditions before awaiting flags or remote values
  • async-defer-await - Move await into branches where actually used
  • async-parallel - Use Promise.all() for independent operations
  • async-dependencies - Use better-all for partial dependencies
  • async-api-routes - Start promises early, await late in API routes
  • async-suspense-boundaries - Use Suspense to stream content

2. Bundle Size Optimization (CRITICAL)

  • bundle-barrel-imports - Import directly, avoid barrel files
  • bundle-analyzable-paths - Prefer statically analyzable import and file-system paths to avoid broad bundles and traces
  • bundle-dynamic-imports - Use next/dynamic for heavy components
  • bundle-defer-third-party - Load analytics/logging after hydration
  • bundle-conditional - Load modules only when feature is activated
  • bundle-preload - Preload on hover/focus for perceived speed

3. Server-Side Performance (HIGH)

  • server-auth-actions - Authenticate server actions like API routes
  • server-cache-react - Use React.cache() for per-request deduplication
  • server-cache-lru - Use LRU cache for cross-request caching
  • server-dedup-props - Avoid duplicate serialization in RSC props
  • server-hoist-static-io - Hoist static I/O (fonts, logos) to module level
  • server-no-shared-module-state - Avoid module-level mutable request state in RSC/SSR
  • server-serialization - Minimize data passed to client components
  • server-parallel-fetching - Restructure components to parallelize fetches
  • server-parallel-nested-fetching - Chain nested fetches per item in Promise.all
  • server-after-nonblocking - Use after() for non-blocking operations

4. Client-Side Data Fetching (MEDIUM-HIGH)

  • client-swr-dedup - Use SWR for automatic request deduplication
  • client-event-listeners - Deduplicate global event listeners
  • client-passive-event-listeners - Use passive listeners for scroll
  • client-localstorage-schema - Version and minimize localStorage data

5. Re-render Optimization (MEDIUM)

  • rerender-defer-reads - Don't subscribe to state only used in callbacks
  • rerender-memo - Extract expensive work into memoized components
  • rerender-memo-with-default-value - Hoist default non-primitive props
  • rerender-dependencies - Use primitive dependencies in effects
  • rerender-derived-state - Subscribe to derived booleans, not raw values
  • rerender-derived-state-no-effect - Derive state during render, not effects
  • rerender-functional-setstate - Use functional setState for stable callbacks
  • rerender-lazy-state-init - Pass function to useState for expensive values
  • rerender-simple-expression-in-memo - Avoid memo for simple primitives
  • rerender-split-combined-hooks - Split hooks with independent dependencies
  • rerender-move-effect-to-event - Put interaction logic in event handlers
  • rerender-transitions - Use startTransition for non-urgent updates
  • rerender-use-deferred-value - Defer expensive renders to keep input responsive
  • rerender-use-ref-transient-values - Use refs for transient frequent values
  • rerender-no-inline-components - Don't define components inside components

6. Rendering Performance (MEDIUM)

  • rendering-animate-svg-wrapper - Animate div wrapper, not SVG element
  • rendering-content-visibility - Use content-visibility for long lists
  • rendering-hoist-jsx - Extract static JSX outside components
  • rendering-svg-precision - Reduce SVG coordinate precision
  • rendering-hydration-no-flicker - Use inline script for client-only data
  • rendering-hydration-suppress-warning - Suppress expected mismatches
  • rendering-activity - Use Activity component for show/hide
  • rendering-conditional-render - Use ternary, not && for conditionals
  • rendering-usetransition-loading - Prefer useTransition for loading state
  • rendering-resource-hints - Use React DOM resource hints for preloading
  • rendering-script-defer-async - Use defer or async on script tags

7. JavaScript Performance (LOW-MEDIUM)

  • js-batch-dom-css - Group CSS changes via classes or cssText
  • js-index-maps - Build Map for repeated lookups
  • js-cache-property-access - Cache object properties in loops
  • js-cache-function-results - Cache function results in module-level Map
  • js-cache-storage - Cache localStorage/sessionStorage reads
  • js-combine-iterations - Combine multiple filter/map into one loop
  • js-length-check-first - Check array length before expensive comparison
  • js-early-exit - Return early from functions
  • js-hoist-regexp - Hoist RegExp creation outside loops
  • js-min-max-loop - Use loop for min/max instead of sort
  • js-set-map-lookups - Use Set/Map for O(1) lookups
  • js-tosorted-immutable - Use toSorted() for immutability
  • js-flatmap-filter - Use flatMap to map and filter in one pass
  • js-request-idle-callback - Defer non-critical work to browser idle time

8. Advanced Patterns (LOW)

  • advanced-effect-event-deps - Don't put useEffectEvent results in effect deps
  • advanced-event-handler-refs - Store event handlers in refs
  • advanced-init-once - Initialize app once per app load
  • advanced-use-latest - useLatest for stable callback refs

How to Use

Read individual rule files for detailed explanations and code examples:

rules/async-parallel.md
rules/bundle-barrel-imports.md

Each rule file contains:

  • Brief explanation of why it matters
  • Incorrect code example with explanation
  • Correct code example with explanation
  • Additional context and references

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

Related by task

from this repository

More skills

All skills
vercel-labs
Official

web-design-guidelines

Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".

Total installs
889.3K
GitHub stars
34.7K
Updated
Nov 20
vercel-labs
Official

vercel-composition-patterns

React composition patterns that scale. Use when refactoring components with boolean prop proliferation, building flexible component libraries, or designing reusable APIs. Triggers on tasks involving compound components, render props, context providers, or component architecture. Includes React 19 API changes.

Total installs
466.4K
GitHub stars
34.7K
Updated
Nov 20
vercel-labs
Official

vercel-react-native-skills

React Native and Expo best practices for building performant mobile apps. Use when building React Native components, optimizing list performance, implementing animations, or working with native modules. Triggers on tasks involving React Native, Expo, mobile performance, or native platform APIs.

Total installs
285.4K
GitHub stars
34.7K
Updated
Nov 20
vercel-labs
Official

vercel-react-view-transitions

Guide for implementing smooth, native-feeling animations using React's View Transition API ( component, addTransitionType, and CSS view transition pseudo-elements). Use this skill whenever the user wants to add page transitions, animate route changes, create shared element animations, animate enter/exit of components, animate list reorder, implement directional (forward/back) navigation animations, or integrate view transitions in Next.js. Also use when the user mentions view transitions, startV

Total installs
199K
GitHub stars
34.7K
Updated
Nov 20