playbooks

home / skills / yldgio / codereview-skills / vercel-react-best-practices

vercel-react-best-practices skill

/skills/vercel-react-best-practices

This skill helps you apply Vercel React and Next.js performance best practices to writing, reviewing, and refactoring code for faster, more reliable

This is most likely a fork of the vercel-react-best-practices skill from lobehub
npx playbooks add skill yldgio/codereview-skills --skill vercel-react-best-practices

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
8.6 KB
---
name: vercel-react-best-practices
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.
license: MIT
metadata:
  author: vercel
  version: "1.0.0"
  source: https://github.com/vercel-labs/agent-skills
---

# 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.

## Security Notice (Critical)

**IMPORTANT: Code security must be maintained during performance optimization.**
- Never expose sensitive data when optimizing data serialization
- Sanitize user-supplied code before rendering or evaluation
- Validate all dynamic output to prevent injection attacks
- Never use HTML comments (`<!-- -->`) to store sensitive information
- Avoid direct evaluation or insertion of code samples without validation

## 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

## Understanding the Rules

Each rule includes:
- **Name**: Identifier for the optimization pattern
- **Description**: Concise explanation of what the rule addresses
- **Code Examples**: Showing incorrect (before) and correct (after) implementations
- **Impact Level**: Priority rating to guide optimization efforts

### Rule Enforcement

When reviewing code:
- **Critical rules**: Must be addressed immediately (waterfalls, bundle bloat)
- **High rules**: Should be fixed in current PR if feasible
- **Medium rules**: Note for future optimization or current work if easy
- **Low rules**: Consider for dedicated performance optimization efforts

## 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 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-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-serialization` - Minimize data passed to client components
- `server-parallel-fetching` - Restructure components to parallelize fetches
- `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-move-effect-to-event` - Put interaction logic in event handlers
- `rerender-transitions` - Use startTransition for non-urgent updates
- `rerender-use-ref-transient-values` - Use refs for transient frequent values

### 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

### 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

### 8. Advanced Patterns (LOW)

- `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

## Additional Best Practices

### Accessibility (a11y)

Ensure performance optimizations don't compromise accessibility:
- Lazy loading must not break keyboard navigation
- Dynamic imports should maintain focus management
- Animations should respect `prefers-reduced-motion`
- Loading states should be announced to screen readers
- Use semantic HTML even when optimizing for performance

### Testing and Error Boundaries

Integrate performance with reliability:
- Test code coverage after refactoring for performance
- Implement error boundaries around Suspense boundaries
- Test lazy-loaded components in isolation
- Validate that optimizations don't break functionality
- Monitor error rates after performance changes

### Next.js Rendering Modes

Choose appropriate rendering strategy based on content requirements:
- **SSG (Static)**: For content that rarely changes
- **ISR (Incremental Static)**: For content with predictable update patterns
- **SSR (Server-Side)**: For personalized or real-time content
- **CSR (Client-Side)**: For highly interactive, user-specific data
- Document rendering mode choices clearly in code comments, but never include secrets (API keys, tokens), credentials, or internal-only endpoints in comments

### State Management and Context (Essential)
- Split contexts by update frequency
- Use context selectors to minimize re-renders
- Keep context providers close to consumers
- Avoid prop drilling by using composition patterns

### Advanced State Patterns
- Consider external stores (Zustand, Jotai) for global state

### Monitoring and Profiling

Measure performance impact:
- Use React DevTools Profiler for component performance
- Monitor Core Web Vitals (LCP, FID, CLS)
- Track bundle size changes in CI/CD
- Set performance budgets for routes
- Profile before and after optimizations
- Use Lighthouse CI for automated performance checks

Overview

This skill provides concise, prioritized React and Next.js performance optimization guidelines derived from Vercel Engineering. It helps engineers write, review, and refactor code to reduce waterfalls, shrink bundles, and improve both server and client performance. Use it as an actionable checklist while making changes to components, pages, and data fetching logic.

How this skill works

The skill inspects tasks involving React components, Next.js pages, data fetching, and bundle patterns, and maps them to high-impact rules grouped by priority. It highlights critical anti-patterns (like waterfalls and large barrel imports), recommends concrete replacements (Promise.all, dynamic imports, React.cache), and reminds you to preserve security, accessibility, and correctness. Rules carry priority levels to guide triage and enforcement.

When to use it

  • Writing new React components or Next.js pages to prevent regressions
  • Reviewing pull requests for performance regressions or bottlenecks
  • Refactoring code to reduce bundle size or eliminate render waterfalls
  • Implementing or optimizing data fetching (SSR, SSG, ISR, CSR)
  • Designing state management or context to minimize re-renders

Best practices

  • Eliminate waterfall fetches: start promises early and await in parallel (Promise.all) or use Suspense boundaries
  • Optimize bundle size: import directly, use next/dynamic for heavy components, and defer nonessential third-party code
  • Server-side: minimize serialized props, use React.cache or LRU caches, and parallelize fetches across components
  • Client-side: use deduping fetch libraries (SWR), passive event listeners for scroll, and version localStorage schemas
  • Re-rendering: memoize expensive components, use primitive deps in effects, and prefer functional state updates
  • Measure: profile with React DevTools, track Core Web Vitals, and set performance budgets in CI

Example use cases

  • Refactor a page that sequentially awaits multiple independent API calls into parallel fetches to remove a waterfall
  • Replace a heavy analytics import with a dynamic, deferred load that triggers after hydration
  • Limit serialized props for an SSR page and cache repeated requests with React.cache or an LRU layer
  • Split a large context into smaller providers or use context selectors to avoid broad re-renders
  • Introduce Suspense boundaries and lazy-load noncritical UI to speed initial render

FAQ

Will these optimizations affect accessibility?

No—follow accessibility notes: preserve focus, announce loading states, respect prefers-reduced-motion, and keep semantic HTML when applying lazy-loading or dynamic imports.

How do I prioritize fixes?

Fix critical rules first (waterfalls, bundle bloat), then high server-side issues, followed by client and re-render optimizations; track medium/low items for focused performance work.

How do I avoid introducing security risks while optimizing?

Never expose secrets in serialized props or comments, sanitize user-supplied code, validate dynamic output, and avoid direct evaluation of untrusted content.