| 1 | --- |
| 2 | name: vercel-react-best-practices |
| 3 | description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements. |
| 4 | license: MIT |
| 5 | metadata: |
| 6 | author: vercel |
| 7 | version: "1.0.0" |
| 8 | --- |
| 9 | |
| 10 | # Vercel React Best Practices |
| 11 | |
| 12 | Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 69 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation. |
| 13 | |
| 14 | ## When to Apply |
| 15 | |
| 16 | Reference these guidelines when: |
| 17 | - Writing new React components or Next.js pages |
| 18 | - Implementing data fetching (client or server-side) |
| 19 | - Reviewing code for performance issues |
| 20 | - Refactoring existing React/Next.js code |
| 21 | - Optimizing bundle size or load times |
| 22 | |
| 23 | ## Rule Categories by Priority |
| 24 | |
| 25 | | Priority | Category | Impact | Prefix | |
| 26 | |----------|----------|--------|--------| |
| 27 | | 1 | Eliminating Waterfalls | CRITICAL | `async-` | |
| 28 | | 2 | Bundle Size Optimization | CRITICAL | `bundle-` | |
| 29 | | 3 | Server-Side Performance | HIGH | `server-` | |
| 30 | | 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` | |
| 31 | | 5 | Re-render Optimization | MEDIUM | `rerender-` | |
| 32 | | 6 | Rendering Performance | MEDIUM | `rendering-` | |
| 33 | | 7 | JavaScript Performance | LOW-MEDIUM | `js-` | |
| 34 | | 8 | Advanced Patterns | LOW | `advanced-` | |
| 35 | |
| 36 | ## Quick Reference |
| 37 | |
| 38 | ### 1. Eliminating Waterfalls (CRITICAL) |
| 39 | |
| 40 | - `async-cheap-condition-before-await` - Check cheap sync conditions before awaiting flags or remote values |
| 41 | - `async-defer-await` - Move await into branches where actually used |
| 42 | - `async-parallel` - Use Promise.all() for independent operations |
| 43 | - `async-dependencies` - Use better-all for partial dependencies |
| 44 | - `async-api-routes` - Start promises early, await late in API routes |
| 45 | - `async-suspense-boundaries` - Use Suspense to stream content |
| 46 | |
| 47 | ### 2. Bundle Size Optimization (CRITICAL) |
| 48 | |
| 49 | - `bundle-barrel-imports` - Import directly, avoid barrel files |
| 50 | - `bundle-dynamic-imports` - Use next/dynamic for heavy components |
| 51 | - `bundle-defer-third-party` - Load analytics/logging after hydration |
| 52 | - `bundle-conditional` - Load modules only when feature is activated |
| 53 | - `bundle-preload` - Preload on hover/focus for perceived speed |
| 54 | |
| 55 | ### 3. Server-Side Performance (HIGH) |
| 56 | |
| 57 | - `server-auth-actions` - Authenticate server actions like API routes |
| 58 | - `server-cache-react` - Use React.cache() for per-request deduplication |
| 59 | - `server-cache-lru` - Use LRU cache for cross-request caching |
| 60 | - `server-dedup-props` - Avoid duplicate serialization in RSC props |
| 61 | - `server-hoist-static-io` - Hoist static I/O (fonts, logos) to module level |
| 62 | - `server-no-shared-module-state` - Avoid module-level mutable request state in RSC/SSR |
| 63 | - `server-serialization` - Minimize data passed to client components |
| 64 | - `server-parallel-fetching` - Restructure components to parallelize fetches |
| 65 | - `server-parallel-nested-fetching` - Chain nested fetches per item in Promise.all |
| 66 | - `server-after-nonblocking` - Use after() for non-blocking operations |
| 67 | |
| 68 | ### 4. Client-Side Data Fetching (MEDIUM-HIGH) |
| 69 | |
| 70 | - `client-swr-dedup` - Use SWR for automatic request deduplication |
| 71 | - `client-event-listeners` - Deduplicate global event listeners |
| 72 | - `client-passive-event-listeners` - Use passive listeners for scroll |
| 73 | - `client-localstorage-schema` - Version and minimize localStorage data |
| 74 | |
| 75 | ### 5. Re-render Optimization (MEDIUM) |
| 76 | |
| 77 | - `rerender-defer-reads` - Don't subscribe to state only used in callbacks |
| 78 | - `rerender-memo` - Extract expensive work into memoized components |
| 79 | - `rerender-memo-with-default-value` - Hoist default non-primitive props |
| 80 | - `rerender-dependencies` - Use primitive dependencies in effects |
| 81 | - `rerender-derived-state` - Subscribe to derived booleans, not raw values |
| 82 | - `rerender-derived-state-no-effect` - Derive state during render, not effects |
| 83 | - `rerender-functional-setstate` - Use functional setState for stable callbacks |
| 84 | - `rerender-lazy-state-init` - Pass function to useState for expensive values |
| 85 | - `rerender-simple-expression-in-memo` - Avoid memo for simple primitives |
| 86 | - `rerender-split-combined-hooks` - Split hooks with independent dependencies |
| 87 | - `rerender-move-effect-to-event` - Put interaction logic in event handlers |
| 88 | - `rerender-transitions` - Use startTransition for non-urgent updates |
| 89 | - `rerender-use-deferred-value` - Defer expensive renders to keep input responsive |
| 90 | - `rerender-use-ref-transient-values` - Use refs for transient frequent values |
| 91 | - `rerender-no-inline-components` - Don't define components inside components |
| 92 | |
| 93 | ### 6. Rendering Performance (MEDIUM) |
| 94 | |
| 95 | - `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element |
| 96 | - `rendering-content-visibility` - Use content-visibility for long lists |
| 97 | - `rendering-hoist-jsx` - Extract static JSX outside components |
| 98 | - `rendering-svg-precision` - Reduce SVG coordinate precision |
| 99 | - `rendering-hydration-no-flicker` - Use inline script for client-only data |
| 100 | - `rendering-hydration-suppress-warning` - Suppress expected mismatches |
| 101 | - `rendering-activity` - Use Activity component for show/hide |
| 102 | - `rendering-conditional-render` - Use ternary, not && for conditionals |
| 103 | - `rendering-usetransition-loading` - Prefer useTransition for loading state |
| 104 | - `rendering-resource-hints` - Use React DOM resource hints for preloading |
| 105 | - `rendering-script-defer-async` - Use defer or async on script tags |
| 106 | |
| 107 | ### 7. JavaScript Performance (LOW-MEDIUM) |
| 108 | |
| 109 | - `js-batch-dom-css` - Group CSS changes via classes or cssText |
| 110 | - `js-index-maps` - Build Map for repeated lookups |
| 111 | - `js-cache-property-access` - Cache object properties in loops |
| 112 | - `js-cache-function-results` - Cache function results in module-level Map |
| 113 | - `js-cache-storage` - Cache localStorage/sessionStorage reads |
| 114 | - `js-combine-iterations` - Combine multiple filter/map into one loop |
| 115 | - `js-length-check-first` - Check array length before expensive comparison |
| 116 | - `js-early-exit` - Return early from functions |
| 117 | - `js-hoist-regexp` - Hoist RegExp creation outside loops |
| 118 | - `js-min-max-loop` - Use loop for min/max instead of sort |
| 119 | - `js-set-map-lookups` - Use Set/Map for O(1) lookups |
| 120 | - `js-tosorted-immutable` - Use toSorted() for immutability |
| 121 | - `js-flatmap-filter` - Use flatMap to map and filter in one pass |
| 122 | - `js-request-idle-callback` - Defer non-critical work to browser idle time |
| 123 | |
| 124 | ### 8. Advanced Patterns (LOW) |
| 125 | |
| 126 | - `advanced-effect-event-deps` - Don't put `useEffectEvent` results in effect deps |
| 127 | - `advanced-event-handler-refs` - Store event handlers in refs |
| 128 | - `advanced-init-once` - Initialize app once per app load |
| 129 | - `advanced-use-latest` - useLatest for stable callback refs |
| 130 | |
| 131 | ## How to Use |
| 132 | |
| 133 | Read individual rule files for detailed explanations and code examples: |
| 134 | |
| 135 | ``` |
| 136 | rules/async-parallel.md |
| 137 | rules/bundle-barrel-imports.md |
| 138 | ``` |
| 139 | |
| 140 | Each rule file contains: |
| 141 | - Brief explanation of why it matters |
| 142 | - Incorrect code example with explanation |
| 143 | - Correct code example with explanation |
| 144 | - Additional context and references |
| 145 | |
| 146 | ## Full Compiled Document |
| 147 | |
| 148 | For the complete guide with all rules expanded: `AGENTS.md` |
| 149 |