React Best Practices Skill for Claude Code: 40+ Performance Optimization Rules

What is the React Best Practices Skill?

The React Best Practices skill is a comprehensive performance optimization guide for React and Next.js applications. It provides Claude Code with 40+ actionable rules organized by impact level, helping you eliminate performance bottlenecks, reduce bundle sizes, and improve user experience.

This skill was created by Vercel Engineering and includes real-world examples and code comparisons for each optimization rule.

graph TD
    A[🎯 Performance Issue] --> B[🤖 Claude + React Best Practices]
    B --> C[📊 Analyze Bottleneck]
    C --> D{Issue Type?}
    D -->|Critical| E[⚡ Eliminate Waterfalls]
    D -->|Critical| F[📦 Optimize Bundle Size]
    D -->|High| G[🚀 Server-Side Performance]
    D -->|Medium| H[🔄 Re-render Optimization]
    E --> I[✅ Optimized App]
    F --> I
    G --> I
    H --> I

    style B fill:#F97316,stroke:#fff,color:#000
    style I fill:#00ff41,stroke:#fff,color:#000

Why You Need This Skill

Performance optimization can be overwhelming. With so many possible improvements, it's hard to know where to start. This skill solves that problem by:

Prioritizing optimizations - Rules are organized by impact (CRITICAL, HIGH, MEDIUM, LOW)
Providing proven patterns - Each rule includes correct/incorrect code examples
Measuring impact - Clear guidelines help you understand the value of each optimization
Progressive context loading - The skill loads detailed guidelines on-demand to minimize token usage

Key Optimization Categories

1. Eliminating Waterfalls (CRITICAL)

Waterfalls are a major performance killer. Each sequential await adds full network latency. This category teaches you to:

Defer await until needed
Use Promise.all() for parallel operations
Prevent waterfall chains in API routes
Implement strategic Suspense boundaries

// ❌ Sequential waterfalls (slow)
const user = await fetchUser()
const posts = await fetchPosts()
const comments = await fetchComments()

// ✅ Parallel fetching (fast)
const [user, posts, comments] = await Promise.all([
  fetchUser(),
  fetchPosts(),
  fetchComments()
])

2. Bundle Size Optimization (CRITICAL)

Reducing initial bundle size improves Time to Interactive (TTI) and Largest Contentful Paint (LCP):

Avoid barrel file imports
Use dynamic imports for heavy components
Defer non-critical third-party libraries
Preload based on user intent

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

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

3. Server-Side Performance (HIGH)

Optimize React Server Components 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. 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
Use transitions for non-urgent updates

Installation

Install the React Best Practices skill using the Claude Code Templates CLI:

npx claude-code-templates@latest --skill=web-development/react-best-practices --yes

Where is the skill installed?

The skill is saved in .claude/skills/react-best-practices/ in your project directory:

your-project/
├── .claude/
│   └── skills/
│       └── react-best-practices/    # ← Skill installed here
│           ├── SKILL.md
│           └── references/
│               └── react-performance-guidelines.md
├── src/
│   └── components/
├── package.json
└── README.md

How to Use the Skill

The skill uses progressive context loading - it provides a quick reference first, then loads detailed guidelines only when needed. This approach minimizes token usage while giving you access to comprehensive information.

Basic Usage

# Start Claude Code
claude

# Request optimization help
> Use the react-best-practices skill to optimize my ProductList component that's loading slowly

Claude will:

Load the skill's quick reference
Analyze your component
Identify the optimization category (e.g., waterfalls, bundle size)
Load detailed guidelines for that specific category
Provide specific recommendations with code examples

Usage Examples

Example 1: Eliminate Data Fetching Waterfalls

claude

> Use the react-best-practices skill to review this component and eliminate any waterfalls:

async function Dashboard() {
  const user = await fetchUser()
  const posts = await fetchPosts(user.id)
  const stats = await fetchStats(user.id)
  return <div>...</div>
}

Result: Claude identifies the sequential awaits, loads the "Eliminating Waterfalls" guidelines, and refactors the code to use Promise.all() for parallel fetching.

Example 2: Reduce Bundle Size

claude

> Use the react-best-practices skill to optimize the bundle size of my app. I'm importing lucide-react and lodash

Result: Claude loads the "Bundle Size Optimization" guidelines and recommends direct imports instead of barrel imports, potentially saving hundreds of KB.

Example 3: Optimize Re-renders

claude

> Use the react-best-practices skill to fix unnecessary re-renders in my form component

Result: Claude analyzes the component, loads "Re-render Optimization" rules, and suggests extracting to memoized components, narrowing dependencies, or using transitions.

Key Metrics to Track

The skill helps you optimize for these critical web performance metrics:

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 Avoided

The skill helps you avoid these common React performance mistakes:

❌ Using barrel imports from large libraries
❌ Blocking parallel operations with sequential awaits
❌ Re-rendering entire trees when only part needs updating
❌ Loading analytics/tracking in the critical path
❌ Mutating arrays with .sort() instead of .toSorted()
❌ Creating RegExp or heavy objects inside render

Progressive Context Loading

One of the unique features of this skill is its progressive context loading system:

Quick Reference - Loads first with critical priorities and common patterns
Category Overview - High-level description of optimization categories
Detailed Guidelines - Full documentation loaded on-demand from references folder

This approach ensures you get the information you need without overwhelming Claude's context window.

Official Documentation

For more information about skills in Claude Code, see the official skills documentation.

React Best Practices Skill: 40+ Performance Optimization Rules