react-best-practices
npx machina-cli add skill runkids/my-skills/react-best-practices --openclawReact Best Practices
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:
| Priority | Category | Impact |
|---|---|---|
| 1 | Eliminating Waterfalls | CRITICAL |
| 2 | Bundle Size Optimization | CRITICAL |
| 3 | Server-Side Performance | HIGH |
| 4 | Client-Side Data Fetching | MEDIUM-HIGH |
| 5 | Re-render Optimization | MEDIUM |
| 6 | Rendering Performance | MEDIUM |
| 7 | JavaScript Performance | LOW-MEDIUM |
| 8 | Advanced Patterns | LOW |
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-allfor partial dependencies - Use Suspense boundaries to stream content
Reduce Bundle Size:
- Avoid barrel file imports (import directly from source)
- Use
next/dynamicfor 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
startTransitionfor non-urgent updates
Rendering Patterns
- Animate SVG wrappers, not SVG elements directly
- Use
content-visibility: autofor 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 ofsort()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 patternsreferences/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 patternsbundle-*- Bundle size optimizationserver-*- Server-side performanceclient-*- Client-side data fetchingrerender-*- Re-render optimizationrendering-*- DOM rendering performancejs-*- JavaScript micro-optimizationsadvanced-*- Advanced patterns
Source
git clone https://github.com/runkids/my-skills/blob/main/frontend/react/react-best-practices/SKILL.mdView on GitHub Overview
Comprehensive performance optimization guide for React and Next.js apps, with 40+ rules across 8 categories. The rules are prioritized by impact to guide automated refactoring and code generation, helping you write, review, or refactor for faster load times and better UX. It covers patterns from waterfall elimination to bundle optimization and server/client performance improvements.
How This Skill Works
Developers apply the guidelines in a priority order, starting with eliminating waterfalls and reducing bundle size, then addressing server-side and client-side patterns. The guide provides concrete patterns (e.g., Promise.all, next/dynamic, SWR, startTransition, content-visibility) and maps them to common tasks like data fetching and rendering, enabling targeted refactoring and codegen.
When to Use It
- 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
Quick Start
- Step 1: Audit React components and Next.js pages for waterfalls, large bundles, and heavy server/client fetches.
- Step 2: Apply patterns in priority order: deferring awaits, Promise.all, dynamic imports, SWR, and startTransition where appropriate.
- Step 3: Measure impact with Lighthouse, Web Vitals, and bundle analysis; iterate until targets are met.
Best Practices
- Eliminate waterfalls: defer awaits until needed, start independent async tasks early with Promise.all, and use Suspense boundaries when streaming content.
- Reduce bundle size: import directly from source (avoid barrel imports), use next/dynamic for heavy components, defer non-critical libraries, and preload based on user intent.
- Server-side performance: apply per-request deduplication with React.cache(), use an LRU cache for cross-request caching, minimize serialization at RSC boundaries, and parallelize data fetching via component composition.
- Client-side data fetching: use SWR for automatic request deduplication, defer state reads to the point of use, and initialize expensive values lazily.
- Rendering and JavaScript: optimize with content-visibility: auto for long lists, avoid hydration mismatches with inline scripts, and use toSorted() for immutable sorts.
Example Use Cases
- Refactor a Next.js page that fetches three APIs to use Promise.all and a Suspense boundary for streaming content.
- Split a heavy dashboard widget into a dynamically loaded component with next/dynamic to reduce initial bundle size.
- Defer loading a non-critical analytics library until user interaction.
- Replace repetitive API calls on a feed with SWR to deduplicate requests and cache results.
- Introduce per-request deduplication using React.cache() and add an LRUCross-request cache for expensive data.
