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
- Identify the target page or component, its framework version and the behavior or loading problem you want to investigate.
- Start with the waterfall and bundle categories, then inspect the categories that match the code under review.
- Read the relevant rule file or its expanded AGENTS.md section instead of relying on the one-line index alone.
- Check the proposed change against real dependencies, request scope, authorization and supported APIs.
- 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-practicesSource information
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
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Eliminating Waterfalls | CRITICAL | async- |
| 2 | Bundle Size Optimization | CRITICAL | bundle- |
| 3 | Server-Side Performance | HIGH | server- |
| 4 | Client-Side Data Fetching | MEDIUM-HIGH | client- |
| 5 | Re-render Optimization | MEDIUM | rerender- |
| 6 | Rendering Performance | MEDIUM | rendering- |
| 7 | JavaScript Performance | LOW-MEDIUM | js- |
| 8 | Advanced Patterns | LOW | advanced- |
Quick Reference
1. Eliminating Waterfalls (CRITICAL)
async-cheap-condition-before-await- Check cheap sync conditions before awaiting flags or remote valuesasync-defer-await- Move await into branches where actually usedasync-parallel- Use Promise.all() for independent operationsasync-dependencies- Use better-all for partial dependenciesasync-api-routes- Start promises early, await late in API routesasync-suspense-boundaries- Use Suspense to stream content
2. Bundle Size Optimization (CRITICAL)
bundle-barrel-imports- Import directly, avoid barrel filesbundle-analyzable-paths- Prefer statically analyzable import and file-system paths to avoid broad bundles and tracesbundle-dynamic-imports- Use next/dynamic for heavy componentsbundle-defer-third-party- Load analytics/logging after hydrationbundle-conditional- Load modules only when feature is activatedbundle-preload- Preload on hover/focus for perceived speed
3. Server-Side Performance (HIGH)
server-auth-actions- Authenticate server actions like API routesserver-cache-react- Use React.cache() for per-request deduplicationserver-cache-lru- Use LRU cache for cross-request cachingserver-dedup-props- Avoid duplicate serialization in RSC propsserver-hoist-static-io- Hoist static I/O (fonts, logos) to module levelserver-no-shared-module-state- Avoid module-level mutable request state in RSC/SSRserver-serialization- Minimize data passed to client componentsserver-parallel-fetching- Restructure components to parallelize fetchesserver-parallel-nested-fetching- Chain nested fetches per item in Promise.allserver-after-nonblocking- Use after() for non-blocking operations
4. Client-Side Data Fetching (MEDIUM-HIGH)
client-swr-dedup- Use SWR for automatic request deduplicationclient-event-listeners- Deduplicate global event listenersclient-passive-event-listeners- Use passive listeners for scrollclient-localstorage-schema- Version and minimize localStorage data
5. Re-render Optimization (MEDIUM)
rerender-defer-reads- Don't subscribe to state only used in callbacksrerender-memo- Extract expensive work into memoized componentsrerender-memo-with-default-value- Hoist default non-primitive propsrerender-dependencies- Use primitive dependencies in effectsrerender-derived-state- Subscribe to derived booleans, not raw valuesrerender-derived-state-no-effect- Derive state during render, not effectsrerender-functional-setstate- Use functional setState for stable callbacksrerender-lazy-state-init- Pass function to useState for expensive valuesrerender-simple-expression-in-memo- Avoid memo for simple primitivesrerender-split-combined-hooks- Split hooks with independent dependenciesrerender-move-effect-to-event- Put interaction logic in event handlersrerender-transitions- Use startTransition for non-urgent updatesrerender-use-deferred-value- Defer expensive renders to keep input responsivererender-use-ref-transient-values- Use refs for transient frequent valuesrerender-no-inline-components- Don't define components inside components
6. Rendering Performance (MEDIUM)
rendering-animate-svg-wrapper- Animate div wrapper, not SVG elementrendering-content-visibility- Use content-visibility for long listsrendering-hoist-jsx- Extract static JSX outside componentsrendering-svg-precision- Reduce SVG coordinate precisionrendering-hydration-no-flicker- Use inline script for client-only datarendering-hydration-suppress-warning- Suppress expected mismatchesrendering-activity- Use Activity component for show/hiderendering-conditional-render- Use ternary, not && for conditionalsrendering-usetransition-loading- Prefer useTransition for loading staterendering-resource-hints- Use React DOM resource hints for preloadingrendering-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 cssTextjs-index-maps- Build Map for repeated lookupsjs-cache-property-access- Cache object properties in loopsjs-cache-function-results- Cache function results in module-level Mapjs-cache-storage- Cache localStorage/sessionStorage readsjs-combine-iterations- Combine multiple filter/map into one loopjs-length-check-first- Check array length before expensive comparisonjs-early-exit- Return early from functionsjs-hoist-regexp- Hoist RegExp creation outside loopsjs-min-max-loop- Use loop for min/max instead of sortjs-set-map-lookups- Use Set/Map for O(1) lookupsjs-tosorted-immutable- Use toSorted() for immutabilityjs-flatmap-filter- Use flatMap to map and filter in one passjs-request-idle-callback- Defer non-critical work to browser idle time
8. Advanced Patterns (LOW)
advanced-effect-event-deps- Don't putuseEffectEventresults in effect depsadvanced-event-handler-refs- Store event handlers in refsadvanced-init-once- Initialize app once per app loadadvanced-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.mdEach 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

