| name | vercel-react-best-practices |
| description | Use for explicit React or Next.js performance work involving rendering, data fetching, bundles, RSC, hydration, or measured regressions. Do not use for visual design, layout, styling, accessibility, or general component edits; use impeccable for those. Load both only when the request explicitly includes visual design and React performance work. |
| license | MIT |
| metadata | {"author":"vercel","version":"1.0.0"} |
Vercel React Best Practices
Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 57 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
When to Apply
Reference these guidelines when the user asks about React or Next.js performance, or when measurements identify a performance problem:
- Fixing rendering or hydration regressions
- Improving client-side or server-side data fetching
- Reducing bundle size or load times
- Reviewing or refactoring code for a named performance issue
Do not use this skill for visual design, layout, styling, accessibility, or general component work without a performance goal. Use impeccable for those tasks. Load both skills only when the request explicitly includes both concerns.
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-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-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-serialization - Minimize data passed to client componentsserver-parallel-fetching - Restructure components to parallelize fetchesserver-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-move-effect-to-event - Put interaction logic in event handlersrerender-transitions - Use startTransition for non-urgent updatesrerender-use-ref-transient-values - Use refs for transient frequent values
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 state
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 immutability
8. Advanced Patterns (LOW)
advanced-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.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
