name: react-best-practices
description: React performance optimization and best practices. Use when writing React components, hooks, or JSX; refactoring React code; optimizing re-renders, memoization, or state management; reviewing React code for performance issues; fixing hydration mismatches; or implementing transitions, lazy initialization, or effect dependencies. Covers React 19+ features including useEffectEvent, Activity component, and ref props.
license: Apache-2.0
metadata:
author: gohypergiant
version: "1.0"

React Best Practices

Comprehensive performance optimization and best practices for React applications, designed for AI agents and LLMs working with React code.

When to Activate This Skill

Use this skill when the task involves:

Writing React Code

• Creating new React components or hooks
• Writing JSX elements or fragments
• Implementing state management with useState, useReducer, etc.
• Setting up effects with useEffect, useLayoutEffect
• Creating memoized values or components with useMemo, useCallback, memo()

Refactoring React Code

• Optimizing component re-renders
• Reducing unnecessary state updates
• Simplifying complex effect dependencies
• Extracting components for better composition
• Converting class components to functional components

Performance Optimization

• Investigating slow renders or UI jank
• Reducing bundle size (hoisting static JSX, optimizing SVG)
• Implementing lazy loading or code splitting
• Optimizing list rendering (virtualization, content-visibility)
• Fixing memory leaks in effects or subscriptions

React-Specific Issues

• Resolving hydration mismatches in SSR/SSG applications
• Fixing stale closure bugs in callbacks
• Debugging infinite re-render loops
• Preventing unnecessary effect re-runs
• Managing derived state correctly

Code Review

• Reviewing React code for performance anti-patterns
• Identifying improper use of hooks
• Checking for React 19 deprecated patterns (forwardRef, default imports)
• Ensuring proper memoization strategies

When NOT to Use This Skill

Do not activate for:
- General JavaScript/TypeScript questions unrelated to React
- Build configuration (webpack, vite, etc.) unless React-specific
- CSS styling unless related to React performance (animations, content-visibility)
- Backend API development
- Testing setup (use a testing-specific skill if available)

Example Trigger Phrases

This skill should activate when users say things like:

Performance Issues:
- "This component is re-rendering too much"
- "My React app is slow when scrolling"
- "Optimize this React component for performance"
- "The input feels laggy when typing"
- "This page takes forever to load initially"

Debugging Issues:
- "Why is my useEffect running infinitely?"
- "I'm getting hydration errors in Next.js"
- "This callback always has stale/old values"
- "My effect keeps re-subscribing to events"

Code Review:
- "Review this React code for performance issues"
- "Is this React component following best practices?"
- "Can you optimize this React hook?"
- "Check if this component has any performance problems"

React 19 Migration:
- "Update this code to React 19"
- "Replace forwardRef with the new pattern"
- "Fix these React 19 deprecation warnings"
- "Migrate to React 19 best practices"

Refactoring:
- "Refactor this component to be more performant"
- "Clean up these useEffect dependencies"
- "Improve the performance of this list rendering"

How to Use

This skill uses a progressive disclosure structure to minimize context usage:

1. Start with the Overview (AGENTS.md)

Read AGENTS.md for a concise overview of all rules with one-line summaries.

2. Load Specific Rules as Needed

When you identify a relevant optimization, load the corresponding reference file for detailed implementation guidance:

Re-render Optimizations:
- defer-state-reads.md
- extract-memoized-components.md
- narrow-effect-dependencies.md
- subscribe-derived-state.md
- functional-setstate-updates.md
- lazy-state-initialization.md
- transitions-non-urgent-updates.md
- calculate-derived-state.md
- avoid-usememo-simple-expressions.md
- extract-default-parameter-value.md
- interaction-logic-in-event-handlers.md
- useref-for-transient-values.md

Rendering Performance:
- animate-svg-wrapper.md
- css-content-visibility.md
- hoist-static-jsx.md
- optimize-svg-precision.md
- prevent-hydration-mismatch.md
- activity-component-show-hide.md
- hoist-regexp-creation.md
- use-usetransition-over-manual-loading.md

Advanced Patterns:
- store-event-handlers-refs.md
- uselatest-stable-callbacks.md
- cache-repeated-function-calls.md
- initialize-app-once.md

Misc:
- named-imports.md
- no-forwardref.md

Quick References:
- quick-checklists.md
- compound-patterns.md
- react-compiler-guide.md

Automation Scripts:
- scripts/ - Helper scripts to detect anti-patterns

3. Apply the Pattern

Each reference file contains:
- ❌ Incorrect examples showing the anti-pattern
- ✅ Correct examples showing the optimal implementation
- Explanations of why the pattern matters

Examples

Example 1: Optimizing Re-renders

Task: "This component re-renders too frequently when the user scrolls"

Approach:
1. Read AGENTS.md overview
2. Identify likely cause: subscribing to continuous values (scroll position)
3. Load subscribe-derived-state.md or transitions-non-urgent-updates.md
4. Apply the pattern from the reference file

Example 2: Fixing Stale Closures

Task: "This callback always uses the old state value"

Approach:
1. Read AGENTS.md overview
2. Identify issue: stale closure in useCallback
3. Load functional-setstate-updates.md
4. Replace direct state reference with functional update

Example 3: SSR Hydration Mismatch

Task: "Getting hydration errors with localStorage theme"

Approach:
1. Read AGENTS.md overview
2. Identify issue: client-only state causing mismatch
3. Load prevent-hydration-mismatch.md
4. Implement synchronous script pattern

Important Notes

React Compiler Awareness

Many manual optimization patterns (memo, useMemo, useCallback, hoisting static JSX) are automatically handled by React Compiler.

Before optimizing, check if the project uses React Compiler:
- If enabled: Skip manual memoization, but still apply state/effect/CSS optimizations
- If not enabled: Apply all relevant optimizations from this guide

See react-compiler-guide.md for a complete breakdown of what the compiler handles vs what still needs manual optimization.

React 19+ Features

This skill covers React 19 features including:
- useEffectEvent (19.2+) for stable event handlers
- <Activity> component for preserving hidden component state
- ref as a prop (replaces deprecated forwardRef)
- Named imports only (no default import of React)

Performance Philosophy

• Start with correct code, then optimize
• Measure before optimizing
• Optimize slowest operations first (network > rendering > computation)
• Avoid premature optimization of trivial operations

Code Quality Principles

• Prefer simple, readable code over clever optimizations
• Only add complexity when measurements justify it
• Document non-obvious performance optimizations

Additional Resources

Catch up on React 19 features:
- React 19
- React 19.2
- React 19 Upgrade Guide