react-best-practices

name	react-best-practices
description	React and Next.js performance optimization guidelines from Vercel Engineering. Use when writing, reviewing, or refactoring React/Next.js code. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.

React Best Practices

Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 45 rules across 8 categories, prioritized by impact.

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

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

3. Server-Side Performance (HIGH)

• server-cache-react - Use React.cache() for per-request deduplication
• server-serialization - Minimize data passed to client components
• server-parallel-fetching - Restructure components to parallelize fetches

4-5. Client & Re-render Optimization (MEDIUM)

• rerender-defer-reads - Don't subscribe to state only used in callbacks
• rerender-functional-setstate - Use functional setState for stable callbacks
• rerender-transitions - Use startTransition for non-urgent updates

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

7. JavaScript Performance (LOW-MEDIUM)

• js-index-maps - Build Map for repeated lookups
• js-set-map-lookups - Use Set/Map for O(1) lookups
• js-tosorted-immutable - Use toSorted() for immutability

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md