gohypergiant/accelint-react-best-practices

React Best Practices

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

NEVER Do React

These are the most critical anti-patterns that cause real production issues. Experts learned these the hard way through debugging sessions and performance investigations.

NEVER define components inside components — creates new component type on every render, causing full remount with state loss and DOM recreation. Results in input fields losing focus on keystroke, animations restarting unexpectedly, and useEffect cleanup/setup running on every parent render.

NEVER subscribe to searchParams/localStorage if you only read them in callbacks — causes component to re-render on every URL change or storage event even when the component doesn't display those values. Read directly in the callback instead: new URLSearchParams(window.location.search).

NEVER use object/array dependencies in useEffect — triggers effect on every render since objects are recreated with new references each time. Extract primitive values (id, name) from objects and use those as dependencies instead.

NEVER sync derived state with useState + useEffect — leads to extra re-renders, infinite loops, and stale intermediate states. Calculate derived values during render instead: const fullName = firstName + ' ' + lastName.

NEVER use client-only state (localStorage, cookies, device detection) directly in SSR components — causes hydration mismatches where server HTML doesn't match client render, resulting in React warnings, visual flickering, and broken interactivity. Use synchronous inline <script> before React hydrates.

NEVER use forwardRef in React 19+ — deprecated API. Use ref as a regular prop instead: function MyInput({ ref }) { return <input ref={ref} /> }.

NEVER create callbacks/objects/arrays inline as props to memoized components — breaks memoization since new reference is created each render. Extract to module scope, useMemo, or useCallback: const config = useMemo(() => ({ theme }), [theme]).

NEVER put user interaction logic in useEffect — if it's triggered by a button click or form submit, put it directly in the event handler. Effects are for synchronization with external systems, not user-triggered actions.

Before Optimizing Performance, Ask

Before suggesting memo/useMemo/useCallback optimizations, determine if they're needed:

1. Does this project use React Compiler?

   • Search for babel-plugin-react-compiler or react-compiler-webpack-plugin in package.json/config files
   • If yes → Skip manual memoization (memo, useMemo, useCallback, hoisting static JSX) — the compiler handles these automatically
   • If no → Apply all relevant optimizations from this skill
   • See react-compiler-guide.md for what the compiler handles

2. Is this actually a performance problem?

   • Has the user measured/profiled and identified a bottleneck?
   • Or are they asking for a general review/optimization?

3. What's the scale?

   • For lists: How many items? (affects whether to suggest content-visibility vs virtualization)
   • For re-renders: How often does this component re-render?

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
• no-inline-components.md
• useref-for-transient-values.md
• split-combined-hooks.md
• use-deferred-value.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
• effect-event-deps.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

4. Use the Report Template

When this skill is invoked, use the standardized report format:

Template: assets/output-report-template.md

The report format provides:

• Executive Summary with impact assessment
• Severity levels (Critical, High, Medium, Low) for prioritization
• Impact analysis (potential bugs, type safety, maintainability, runtime failures)
• Categorization (Type Safety, Safety, State Management, Return Values, Code Quality)
• Pattern references linking to detailed guidance in references/
• Phase 2 summary table for tracking all issues

When to use the audit template:

• Skill invoked directly via /accelint-react-best-practices <path>
• User asks to "review code quality" or "audit code" across file(s), invoking skill implicitly

When NOT to use the report template:

• User asks to "fix this type error" (direct implementation)
• User asks "what's wrong with this code?" (answer the question)
• User requests specific fixes (apply fixes directly without formal report)

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

Using Skill Patterns Appropriately

Each reference file demonstrates ONE proven pattern, but React problems often have multiple valid solutions.

When applying patterns:

1. ✅ Present the pattern from the reference file
2. ✅ Mention alternative approaches when they exist
3. ✅ Consider user's React version, project complexity, and team preferences
4. ✅ For simple cases, suggest simpler solutions even if not in references

Example: For SSR hydration issues, prevent-hydration-mismatch.md shows the synchronous script approach, but a simple "mounted flag" pattern may be more appropriate for basic use cases.

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