name: 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.

React Best Practices

Attribution: This skill is forked from vercel-labs/agent-skills. All documentation and references are included locally in this repository - no network access required.

Overview

Comprehensive performance optimization guide for React and Next.js applications, containing 40+ rules across 8 categories. Rules are 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

Priority-Ordered Guidelines

Rules are prioritized by impact:

Quick Reference

Critical Patterns (Apply First)

Eliminate Waterfalls:
- Defer await until needed (move into branches)
- Use Promise.all() for independent async operations
- Start promises early, await late
- Use better-all for partial dependencies
- Use Suspense boundaries to stream content

Reduce Bundle Size:
- Avoid barrel file imports (import directly from source)
- Use next/dynamic for heavy components
- Defer non-critical third-party libraries
- Preload based on user intent

High-Impact Server Patterns

• Use React.cache() for per-request deduplication
• Use LRU cache for cross-request caching
• Minimize serialization at RSC boundaries
• Parallelize data fetching with component composition

Medium-Impact Client Patterns

• Use SWR for automatic request deduplication
• Defer state reads to usage point
• Use lazy state initialization for expensive values
• Use derived state subscriptions
• Apply startTransition for non-urgent updates

Rendering Patterns

• Animate SVG wrappers, not SVG elements directly
• Use content-visibility: auto for long lists
• Prevent hydration mismatch with inline scripts
• Use explicit conditional rendering (? : not &&)

JavaScript Patterns

• Batch DOM CSS changes via classes
• Build index maps for repeated lookups
• Cache repeated function calls
• Use toSorted() instead of sort() for immutability
• Early length check for array comparisons

References

Full documentation with code examples is available in:

• references/react-performance-guidelines.md - Complete guide with all patterns
• references/rules/ - Individual rule files organized by category

To look up a specific pattern, grep the rules directory:

grep -l "suspense" references/rules/
grep -l "barrel" references/rules/
grep -l "swr" references/rules/

Rule Categories in references/rules/

• async-* - Waterfall elimination patterns
• bundle-* - Bundle size optimization
• server-* - Server-side performance
• client-* - Client-side data fetching
• rerender-* - Re-render optimization
• rendering-* - DOM rendering performance
• js-* - JavaScript micro-optimizations
• advanced-* - Advanced patterns