react-best-practices

name	react-best-practices
description	Comprehensive React and Next.js performance optimization guide with 40+ rules for eliminating waterfalls, optimizing bundles, and improving rendering. Use when optimizing React apps, reviewing performance, or refactoring components.
version	1.0.0
author	Vercel Engineering
license	MIT
tags	["React","Next.js","Performance","Optimization","Best Practices","Bundle Size","Rendering","Server Components"]
dependencies	[]

React Best Practices - Performance Optimization

Comprehensive performance optimization guide for React and Next.js applications with 40+ rules organized by impact level. Designed to help developers eliminate performance bottlenecks and follow best practices.

When to use this skill

Use React Best Practices when:

• Optimizing React or Next.js application performance
• Reviewing code for performance improvements
• Refactoring existing components for better performance
• Implementing new features with performance in mind
• Debugging slow rendering or loading issues
• Reducing bundle size
• Eliminating request waterfalls

Key areas covered:

• Eliminating Waterfalls (CRITICAL): Prevent sequential async operations
• Bundle Size Optimization (CRITICAL): Reduce initial JavaScript payload
• Server-Side Performance (HIGH): Optimize RSC and data fetching
• Client-Side Data Fetching (MEDIUM-HIGH): Implement efficient caching
• Re-render Optimization (MEDIUM): Minimize unnecessary re-renders
• Rendering Performance (MEDIUM): Optimize browser rendering
• JavaScript Performance (LOW-MEDIUM): Micro-optimizations for hot paths
• Advanced Patterns (LOW): Specialized techniques for edge cases

Quick reference

Critical priorities

1. Defer await until needed - Move awaits into branches where they're used
2. Use Promise.all() - Parallelize independent async operations
3. Avoid barrel imports - Import directly from source files
4. Dynamic imports - Lazy-load heavy components
5. Strategic Suspense - Stream content while showing layout

Common patterns

Parallel data fetching:

const [user, posts, comments] = await Promise.all([
  fetchUser(),
  fetchPosts(),
  fetchComments()
])

Direct imports:

// ❌ Loads entire library
import { Check } from 'lucide-react'

// ✅ Loads only what you need
import Check from 'lucide-react/dist/esm/icons/check'

Dynamic components:

import dynamic from 'next/dynamic'

const MonacoEditor = dynamic(
  () => import('./monaco-editor'),
  { ssr: false }
)

Using the guidelines

The complete performance guidelines are available in the references folder:

• react-performance-guidelines.md: Complete guide with all 40+ rules, code examples, and impact analysis

Each rule includes:

• Incorrect/correct code comparisons
• Specific impact metrics
• When to apply the optimization
• Real-world examples

Categories overview

1. Eliminating Waterfalls (CRITICAL)

Waterfalls are the #1 performance killer. Each sequential await adds full network latency.

• Defer await until needed
• Dependency-based parallelization
• Prevent waterfall chains in API routes
• Promise.all() for independent operations
• Strategic Suspense boundaries

2. Bundle Size Optimization (CRITICAL)

Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.

• Avoid barrel file imports
• Conditional module loading
• Defer non-critical third-party libraries
• Dynamic imports for heavy components
• Preload based on user intent

3. Server-Side Performance (HIGH)

Optimize server-side rendering and data fetching.

• Cross-request LRU caching
• Minimize serialization at RSC boundaries
• Parallel data fetching with component composition
• Per-request deduplication with React.cache()

4. Client-Side Data Fetching (MEDIUM-HIGH)

Automatic deduplication and efficient data fetching patterns.

• Deduplicate global event listeners
• Use SWR for automatic deduplication

5. Re-render Optimization (MEDIUM)

Reduce unnecessary re-renders to minimize wasted computation.

• Defer state reads to usage point
• Extract to memoized components
• Narrow effect dependencies
• Subscribe to derived state
• Use lazy state initialization
• Use transitions for non-urgent updates

6. Rendering Performance (MEDIUM)

Optimize the browser rendering process.

• Animate SVG wrapper instead of SVG element
• CSS content-visibility for long lists
• Hoist static JSX elements
• Optimize SVG precision
• Prevent hydration mismatch without flickering
• Use Activity component for show/hide
• Use explicit conditional rendering

7. JavaScript Performance (LOW-MEDIUM)

Micro-optimizations for hot paths.

• Batch DOM CSS changes
• Build index maps for repeated lookups
• Cache property access in loops
• Cache repeated function calls
• Cache storage API calls
• Combine multiple array iterations
• Early length check for array comparisons
• Early return from functions
• Hoist RegExp creation
• Use loop for min/max instead of sort
• Use Set/Map for O(1) lookups
• Use toSorted() instead of sort()

8. Advanced Patterns (LOW)

Specialized techniques for edge cases.

• Store event handlers in refs
• useLatest for stable callback refs

Implementation approach

When optimizing a React application:

1. Profile first: Use React DevTools Profiler and browser performance tools to identify bottlenecks
2. Focus on critical paths: Start with eliminating waterfalls and reducing bundle size
3. Measure impact: Verify improvements with metrics (LCP, TTI, FID)
4. Apply incrementally: Don't over-optimize prematurely
5. Test thoroughly: Ensure optimizations don't break functionality

Key metrics to track

• Time to Interactive (TTI): When page becomes fully interactive
• Largest Contentful Paint (LCP): When main content is visible
• First Input Delay (FID): Responsiveness to user interactions
• Cumulative Layout Shift (CLS): Visual stability
• Bundle size: Initial JavaScript payload
• Server response time: TTFB for server-rendered content

Common pitfalls to avoid

❌ Don't:

• Use barrel imports from large libraries
• Block parallel operations with sequential awaits
• Re-render entire trees when only part needs updating
• Load analytics/tracking in the critical path
• Mutate arrays with .sort() instead of .toSorted()
• Create RegExp or heavy objects inside render

✅ Do:

• Import directly from source files
• Use Promise.all() for independent operations
• Memoize expensive components
• Lazy-load non-critical code
• Use immutable array methods
• Hoist static objects outside components

Project-specific style preferences

The reference guidelines use function keyword syntax for examples, but this project prefers:

1. Arrow functions for components - Use const Component = memo(() => ...) not memo(function Component() ...)
2. useMemo over IIFE in TSX - Use useMemo(() => ..., [deps]) not (() => { ... })()
3. Implicit returns when possible - Use useMemo(() => value, [deps]) not useMemo(() => { return value }, [deps])
4. Avoid nested ternaries - Use useMemo with early returns or IIFE with if/else blocks for complex conditionals

Resources

• React Documentation
• Next.js Documentation
• SWR Documentation
• Vercel Bundle Optimization
• Vercel Dashboard Performance
• better-all Library
• node-lru-cache

Version history

v0.1.0 (January 2026)

• Initial release from Vercel Engineering
• 40+ performance rules across 8 categories
• Comprehensive code examples and impact analysis