react-best-practices

Original：🇺🇸 English
Not Translated

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.

4installs
Sourceonekeyhq/app-monorepo
Added on

NPX Install

npx skill4agent add onekeyhq/app-monorepo react-best-practices

SKILL.md Content

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:
PriorityCategoryImpact
1Eliminating WaterfallsCRITICAL
2Bundle Size OptimizationCRITICAL
3Server-Side PerformanceHIGH
4Client-Side Data FetchingMEDIUM-HIGH
5Re-render OptimizationMEDIUM
6Rendering PerformanceMEDIUM
7JavaScript PerformanceLOW-MEDIUM
8Advanced PatternsLOW

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