Imported from davidanthonyn/agent-skills (accelint-react-best-practices/AGENTS.md). Install upstream with npx skills add davidanthonyn/agent-skills --skill accelint-react-best-practices. Copyright stays with the author.

React Best Practices

Note: This document is mainly for agents and LLMs to follow when maintaining, generating, or refactoring React code at Accelint. Humans may also find it useful, but guidance here is optimized for automation and consistency by AI-assisted workflows.

Abstract

Comprehensive performance optimization guide for React applications, designed for AI agents and LLMs. Each rule includes one-line summaries with links to detailed examples in references/. Load reference files only when implementing a specific pattern.

⚡ FIRST: Check React Compiler

Before suggesting memo/useMemo/useCallback optimizations:

1. Check if project uses React Compiler (search for babel-plugin-react-compiler or react-compiler-webpack-plugin in package.json/config files)
2. If React Compiler enabled: Skip manual memoization patterns — the compiler handles them automatically. Focus on:
   • State management patterns (functional setState, lazy initialization)
   • Effect patterns (narrow dependencies, stable callbacks)
   • CSS optimizations (content-visibility)
   • SSR/hydration patterns
3. If React Compiler NOT enabled: Apply all optimizations from this skill

See react-compiler-guide.md for details on what the compiler handles vs what still needs manual optimization.

How to Use This Guide

For agents/LLMs:

1. Scan rule summaries below to identify relevant optimizations
2. Load reference files only when implementing a specific pattern
3. Each reference is self-contained with ❌/✅ examples

Quick shortcuts:

• Re-render issues? → Section 1 (Re-render Optimizations)
• Slow rendering? → Section 2 (Rendering Performance)
• Advanced patterns? → Section 3 (Advanced Patterns)
• React 19 migration? → Section 4 (Misc)
• Not sure what's wrong? → Use Quick Diagnostic Guide below

React 19+ Resources:

• React 19 | React 19.2 | Upgrade Guide

Quick Diagnostic Guide

Use this guide to quickly identify which optimization applies based on symptoms:

Symptom → Solution:

• Component re-renders on every parent render → 1.2 Extract to Memoized Components
• Component re-renders when URL/localStorage changes but doesn't display them → 1.1 Defer State Reads
• Effect runs too frequently → 1.3 Narrow Effect Dependencies, 3.1 Store Event Handlers in Refs
• Callback has stale/old values → 1.5 Functional setState Updates, 3.2 useLatest (or useEffectEvent for React 19.2+)
• Slow initial render → 1.6 Lazy State Initialization, 2.3 Hoist Static JSX, 2.7 Hoist RegExp
• Scrolling/interaction feels janky → 2.2 CSS content-visibility, 2.1 Animate SVG Wrapper, 1.7 Transitions
• Typing/input feels sluggish → 1.7 Transitions, 1.15 useDeferredValue for Expensive Derived Renders
• Hook runs expensive computation unnecessarily → 1.14 Split Combined Hook Computations
• Window resize causes excessive re-renders → 1.4 Subscribe to Derived State
• Hydration mismatch errors (SSR/SSG) → 2.5 Prevent Hydration Mismatch
• Component state lost when hiding/showing → 2.6 Activity Component
• Infinite re-render loop → 1.5 Functional setState, 1.3 Narrow Effect Dependencies
• Large bundle size → 2.4 Optimize SVG Precision, 2.3 Hoist Static JSX
• Input fields lose focus on every keystroke → 1.13 Don't Define Components Inside Components
• Animations restart unexpectedly → 1.13 Don't Define Components Inside Components

React 19 Migration Issues:

• "forwardRef is deprecated" → 4.2 No forwardRef
• "Default import from React is deprecated" → 4.1 Named Imports
• Need stable event handlers in effects → 3.1 Store Event Handlers (useEffectEvent)

1. Re-render Optimizations

Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.

1.1 Defer State Reads

Read searchParams/localStorage directly in callbacks instead of subscribing. View detailed examples

1.2 Extract to Memoized Components

Move expensive work into memoized components for early bailout. View detailed examples

1.3 Narrow Effect Dependencies

Use primitive dependencies (id) instead of objects (user) in useEffect. View detailed examples

1.4 Subscribe to Derived State

Subscribe to boolean state (isMobile) instead of continuous values (width). View detailed examples

1.5 Use Functional setState Updates

Use setState(curr => ...) to avoid stale closures and unstable callbacks. View detailed examples

1.6 Use Lazy State Initialization

Use useState(() => expensive()) to avoid re-running initializers. View detailed examples

1.7 Use Transitions for Non-Urgent Updates

Wrap frequent, non-urgent updates in startTransition() to keep UI responsive. View detailed examples

1.8 Calculate Derived State During Rendering

Compute values from props/state during render instead of storing in state or syncing via effects. View detailed examples

1.9 Avoid useMemo For Simple Expressions

Skip useMemo for simple primitives (booleans, numbers, strings). View detailed examples

1.10 Extract Default Non-primitive Parameter Value

Move default object/array/function parameters to constants to preserve memo() optimization. View detailed examples

1.11 Put Interaction Logic in Event Handlers

Run user-triggered side effects (submit, click) in handlers, not state + effect combos. View detailed examples

1.12 Use useRef for Transient Values

Store frequently-changing non-UI values (mouse position, intervals) in refs to avoid re-renders. View detailed examples

1.13 Don't Define Components Inside Components

Define components at module scope, not inside other components to prevent remounting. View detailed examples

1.14 Split Combined Hook Computations

Separate hooks with independent dependencies to avoid unnecessary recomputation. View detailed examples

1.15 Use useDeferredValue for Expensive Derived Renders

Keep user input responsive while deferring expensive computations or renders. View detailed examples

2. Rendering Performance

Optimizing the rendering process reduces the work the browser needs to do.

2.1 Animate SVG Wrapper Instead of SVG Element

Wrap SVG in a div and animate the wrapper for GPU acceleration. View detailed examples

2.2 CSS content-visibility for Long Lists

Apply content-visibility: auto to defer off-screen rendering in long lists. View detailed examples

2.3 Hoist Static JSX Elements

Extract static JSX to module scope to avoid recreating on every render. View detailed examples

2.4 Optimize SVG Precision

Reduce SVG coordinate precision to 1 decimal place with SVGO. View detailed examples

2.5 Prevent Hydration Mismatch Without Flickering

Use inline <script> to sync client-side values before React hydrates. View detailed examples

2.6 Use Activity Component for Show/Hide

Use <Activity mode="visible|hidden"> to preserve state when toggling visibility. View detailed examples

2.7 Hoist RegExp Creation

Create RegExp at module scope or memoize with useMemo to avoid re-creation. View detailed examples

2.8 Use useTransition Over Manual Loading States

Use built-in useTransition with isPending instead of manual loading state management. View detailed examples

3. Advanced Patterns

3.1 Store Event Handlers in Refs

Use useEffectEvent (React 19.2+) to prevent effect re-subscriptions. View detailed examples

3.2 useLatest for Stable Callback Refs

Access latest values in callbacks without adding to dependency arrays. Prefer useEffectEvent for React 19.2+. View detailed examples

3.3 Cache Repeated Function Calls

Use module-level Map cache for expensive computations called repeatedly. View detailed examples

3.4 Initialize App Once, Not Per Mount

Use module-level guards for app-wide initialization instead of component useEffect. View detailed examples

3.5 Do Not Put Effect Events in Dependency Arrays

Never include useEffectEvent functions in dependency arrays — depend on reactive values instead. View detailed examples

4. Misc

4.1 Named Imports

Always use named imports from 'react', not default or wildcard imports. View detailed examples

4.2 No forwardRef

Use ref as a prop instead of forwardRef (deprecated in React 19). View detailed examples

4.3 React Compiler Guide

Understand what React Compiler optimizes automatically vs manual optimizations still needed. View detailed guide

4.4 Quick Reference Checklists

Checklists for common scenarios: new components, performance reviews, SSR, React 19 migration, etc. View checklists

4.5 Compound Pattern Examples

Real-world examples showing multiple optimization patterns working together. View compound patterns