React Best Practices: A Claude Code Skill for Eliminating Performance Bottlenecks

React applications have a well-documented tendency to degrade over time. What starts as a clean, performant codebase accumulates sequential data fetches, barrel imports that inflate bundle sizes, and components that re-render on every state change. By the time performance becomes a visible problem — users complaining about sluggish load times, Lighthouse scores tanking, LCP metrics failing Core Web Vitals thresholds — the codebase has often accumulated months of performance debt that’s hard to untangle without a systematic approach.

The React Best Practices Claude Code skill addresses this directly. It’s a structured, 40+ rule performance optimization guide baked into your Claude Code environment that covers everything from eliminating async waterfalls to reducing bundle size to minimizing unnecessary re-renders. This isn’t a generic “use useMemo sometimes” checklist — it’s an actionable, impact-tiered reference that you can invoke during code reviews, refactoring sessions, or new feature development to catch performance issues before they ship.

When to Use This Skill

This skill earns its keep in several concrete scenarios that most production React teams encounter regularly:

• Pre-launch performance audits: Before shipping a new feature or page, run your components through this skill to catch sequential fetches, heavy synchronous imports, and missing Suspense boundaries.
• Code review assistance: Use it during PR reviews to flag patterns like awaiting inside loops, missing React.cache() deduplication, or direct imports from barrel files.
• Debugging slow TTI or LCP: When Lighthouse or Web Vitals dashboards show regressions, this skill gives Claude Code the context to diagnose whether the root cause is bundle bloat, waterfall chains, or render thrash.
• Next.js RSC migrations: Moving from client components to React Server Components introduces new performance patterns and pitfalls — particularly around serialization at RSC boundaries and cross-request caching.
• Refactoring legacy components: Older React codebases often predate concurrent features. This skill provides a roadmap for incrementally modernizing data fetching and rendering patterns.
• Onboarding senior engineers to existing codebases: A new team member can use this skill as a quick calibration against your existing patterns to identify gaps.

Key Features and Capabilities

The skill organizes its 40+ rules into eight categories, each tagged with an impact level so you can prioritize work correctly:

Eliminating Waterfalls (Critical)

Sequential async operations are the single biggest source of preventable latency in React applications. The skill covers deferring awaits until they’re actually needed, parallelizing independent fetches with Promise.all(), preventing waterfall chains in API routes, and placing Suspense boundaries strategically to enable streaming.

Bundle Size Optimization (Critical)

Initial JavaScript payload directly affects Time to Interactive and Largest Contentful Paint. The rules here cover avoiding barrel file imports, conditional module loading, deferring non-critical third-party libraries, dynamic imports for heavy components, and preloading assets based on user intent signals.

Server-Side Performance (High)

For Next.js apps using the App Router, this section covers cross-request LRU caching, minimizing serialization overhead at RSC boundaries, parallel data fetching via component composition, and using React.cache() for per-request deduplication.

Client-Side Data Fetching (Medium-High)

Efficient client-side fetching patterns with automatic deduplication, preventing redundant network requests across component trees, and cache invalidation strategies.

Re-render Optimization (Medium)

Targeted memoization with useMemo and useCallback, stable reference patterns, and component splitting to isolate render boundaries.

Rendering Performance, JavaScript Performance, and Advanced Patterns

Browser rendering optimizations, micro-optimizations for hot paths, and specialized techniques for edge cases round out the lower-priority tiers — still useful, but correctly deprioritized below waterfall and bundle work.

Quick Start Guide

After installing the skill into your Claude Code environment, you can invoke it conversationally during any performance-related task. Here are practical examples of common use cases:

Parallelizing Independent Data Fetches

One of the most common and highest-impact fixes. Instead of awaiting fetches sequentially:

// ❌ Sequential — adds full network RTT for each fetch
const user = await fetchUser(id)
const posts = await fetchPosts(user.id)
const preferences = await fetchPreferences(user.id)

Parallelize fetches that don’t depend on each other:

// ✅ Parallel — total time = slowest single fetch
const [user, posts, preferences] = await Promise.all([
  fetchUser(id),
  fetchPosts(userId),
  fetchPreferences(userId)
])

Fixing Barrel Import Bloat

Barrel files (index.ts re-exports) force bundlers to include entire libraries even when you only need one component:

// ❌ Pulls in entire lucide-react bundle
import { Check, X, AlertCircle } from 'lucide-react'

// ✅ Loads only the three icons you actually use
import Check from 'lucide-react/dist/esm/icons/check'
import X from 'lucide-react/dist/esm/icons/x'
import AlertCircle from 'lucide-react/dist/esm/icons/alert-circle'

Dynamic Imports for Heavy Components

Components like rich text editors, chart libraries, or code editors shouldn’t be in the initial bundle:

import dynamic from 'next/dynamic'

// ✅ Monaco Editor loads only when the component mounts
const MonacoEditor = dynamic(
  () => import('./monaco-editor'),
  {
    ssr: false,
    loading: () => <EditorSkeleton />
  }
)

Per-Request Deduplication with React.cache()

In Next.js App Router, the same data fetch can be triggered by multiple Server Components in the same render tree:

import { cache } from 'react'

// ✅ Deduplicated — only one DB query per request
// regardless of how many RSCs call this function
export const getUser = cache(async (id: string) => {
  return db.users.findUnique({ where: { id } })
})

Strategic Suspense Boundaries

Streaming lets you show layout immediately while slow data loads in the background:

// ✅ Shell renders immediately, slow content streams in
export default function Dashboard() {
  return (
    <DashboardShell>
      <Suspense fallback={<MetricsSkeleton />}>
        <MetricsPanel />
      </Suspense>
      <Suspense fallback={<FeedSkeleton />}>
        <ActivityFeed />
      </Suspense>
    </DashboardShell>
  )
}

Tips and Best Practices

Start with Critical impact rules

The skill’s impact tiers are meaningful. Waterfall elimination and bundle optimization will move your Core Web Vitals numbers far more than memoization tweaks. Always start with CRITICAL, then HIGH, before touching MEDIUM or LOW tier optimizations.

Measure before and after

Use this skill alongside concrete measurement tooling. Bundle analyzer (@next/bundle-analyzer), Chrome DevTools Performance tab, and Web Vitals RUM data should bracket your optimization sessions. Don’t optimize blind.

Use the skill during code generation, not just review

The highest-leverage use of this skill is invoking it when writing new components or API routes, not just when auditing existing code. Catching a waterfall pattern before it ships is significantly cheaper than refactoring it later.

Be selective with memoization

The skill correctly places re-render optimization at MEDIUM priority. Over-memoizing with useMemo and useCallback introduces its own overhead and code complexity. Apply these only when profiling confirms unnecessary re-renders are causing real slowdowns.

RSC boundary serialization is easy to miss

When passing data from Server Components to Client Components, everything crossing that boundary gets serialized. Passing large objects or deeply nested data structures here is a silent performance tax — the skill’s server-side rules help you spot this pattern.

Preload on intent, not on load

The skill covers preloading assets based on user intent signals (hover, focus, scroll proximity). This is a high-ROI pattern that most teams skip, and it integrates cleanly with Next.js’s router.prefetch() API.

Conclusion

React performance work without a systematic framework tends to produce inconsistent results — teams fix the obvious issues and miss the structural problems. The React Best Practices skill gives Claude Code a comprehensive, impact-tiered ruleset to apply consistently across code reviews, new feature development, and performance debugging sessions.

For senior developers, the value isn’t in learning rules you may already know — it’s in having those rules reliably applied at the point of code generation and review, where they prevent regressions instead of fixing them after the fact. The 40+ rules covering waterfalls, bundle size, RSC patterns, and rendering optimization represent the accumulated knowledge of what actually moves performance metrics in production React applications.

If your team ships React or Next.js code regularly, integrating this skill into your Claude Code workflow is a straightforward way to raise the floor on performance quality across every PR.

Skill template sourced from the claude-code-templates open source project (MIT License).