React Skill

Overview

Modern React patterns using hooks, functional components, and best practices for building maintainable UIs.

Objective

Guide developers in building React applications with proper component architecture, state management, and performance optimization.

When to Use

Use this skill when:

• Creating React functional components or refactoring class components
• Implementing hooks (useState, useEffect, useMemo, useCallback)
• Managing component state and side effects
• Optimizing React performance and preventing unnecessary re-renders
• Building component composition patterns
• Integrating with React ecosystem libraries

Don’t use this skill for:

• Non-React JavaScript patterns (use javascript skill)
• React Native mobile development (use react-native skill)
• Redux state management (use redux-toolkit skill)
• Server-side framework specifics (use astro or relevant framework skill)

📚 Extended Mandatory Read Protocol

This skill has a references/ directory with detailed guides for complex React patterns.

Reading Rules

Read references/ when:

• MUST read hooks-advanced.md when:

  • Deciding useState vs useReducer (4+ related state values)
  • Creating custom hooks or composing hooks
  • Dealing with stale closures or hook dependencies

• MUST read useEffect-patterns.md when:

  • Implementing data fetching, subscriptions, or side effects
  • Handling cleanup, race conditions, or async operations
  • Debugging dependency array issues

• MUST read performance.md when:

  • Components re-rendering unnecessarily
  • Working with expensive computations or large lists
  • Profiling and optimizing React applications

• MUST read context-patterns.md when:

  • Sharing state across multiple components
  • Building compound components or component APIs
  • Optimizing context performance (preventing re-renders)

• MUST read forms-state.md when:

  • Building forms with validation
  • Choosing controlled vs uncontrolled inputs
  • Implementing multi-step forms or file uploads

Quick reference only: Use this SKILL.md for simple components and quick lookups. Decision Tree below directs you to specific references when needed.

Reading Priority

See references/README.md for complete navigation guide.

Critical Patterns

✅ REQUIRED: Use Functional Components with Hooks

// ✅ CORRECT: Functional component with hooks
const Counter: React.FC = () => {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
};

// ❌ WRONG: Class component (legacy pattern)
class Counter extends React.Component {
  state = { count: 0 };
  render() { /* ... */ }
}

✅ REQUIRED: Proper useEffect Dependencies

// ✅ CORRECT: All dependencies included
useEffect(() => {
  fetchData(userId);
}, [userId]);

// ❌ WRONG: Missing dependencies (causes stale closures)
useEffect(() => {
  fetchData(userId);
}, []); // userId missing

✅ REQUIRED: Stable Keys for Lists

// ✅ CORRECT: Use unique IDs
{items.map(item => <li key={item.id}>{item.name}</li>)}

// ❌ WRONG: Using array index (causes bugs on reorder/delete)
{items.map((item, index) => <li key={index}>{item.name}</li>)}

❌ NEVER: Conditional Hook Calls

// ❌ WRONG: Hooks must not be conditional
if (condition) {
  const [value, setValue] = useState(0); // Breaks React rules
}

// ✅ CORRECT: Hooks at top level, conditional logic inside
const [value, setValue] = useState(0);
const shouldUse = condition ? value : defaultValue;

Conventions

Refer to conventions for:

• Code organization
• Naming patterns

Refer to a11y for:

• Semantic HTML in JSX
• Keyboard navigation
• ARIA attributes

React Specific

• Use functional components with hooks
• Implement proper component composition
• Memoize expensive computations with useMemo
• Use useCallback for event handlers in optimized components
• Handle side effects with useEffect
• Provide keys for lists

Decision Tree

Simple state (<3 values)? → Use useState. See hooks-advanced.md for patterns.

Complex state (4+ related values)? → Use useReducer for centralized logic. MUST read hooks-advanced.md for reducer patterns.

Side effect needed? → Use useEffect with proper dependency array. MUST read useEffect-patterns.md for cleanup, race conditions, and async patterns.

Data fetching? → Use useEffect with AbortController. MUST read useEffect-patterns.md#async-patterns for race condition handling.

Performance issue? → Profile first with React DevTools Profiler. MUST read performance.md for useMemo, useCallback, React.memo patterns.

Expensive computation? → Use useMemo if calculation is costly. CHECK performance.md#usememo to decide if worth it.

Passing callbacks to memoized children? → Use useCallback. CHECK performance.md#usecallback for stable references.

Sharing state across components? → Use Context API or lift state. MUST read context-patterns.md for performance optimization and splitting contexts.

Building component API? → Use compound components pattern. CHECK context-patterns.md#compound-components for implicit state sharing.

Form with validation? → Use controlled components. MUST read forms-state.md for controlled vs uncontrolled and validation patterns.

Multi-step form? → Use wizard pattern with step state. CHECK forms-state.md#multi-step-forms.

File upload? → Use controlled input with File API. CHECK forms-state.md#file-uploads for single/multiple uploads with progress.

List rendering? → Always provide stable key prop (use unique IDs, not indices). For large lists (1000+), MUST read performance.md#list-rendering-optimization for virtualization.

Conditional rendering? → Use && for simple conditions, ternary ? : for if-else, early return for complex logic.

Example

import { useState, useEffect, useMemo } from 'react';

interface TodoProps {
  items: string[];
}

const TodoList: React.FC<TodoProps> = ({ items }) => {
  const [filter, setFilter] = useState('');

  const filteredItems = useMemo(() =>
    items.filter(item => item.toLowerCase().includes(filter.toLowerCase())),
    [items, filter]
  );

  return (
    <div>
      <input value={filter} onChange={(e) => setFilter(e.target.value)} />
      <ul>
        {filteredItems.map((item, index) => (
          <li key={index}>{item}</li>
        ))}
      </ul>
    </div>
  );
};

Edge Cases

Stale closures in useEffect: When state/props aren’t in dependency array, closures capture old values. Always include all dependencies or use functional setState: setState(prev => prev + 1).

useEffect cleanup: Return cleanup function for subscriptions, timers, event listeners to prevent memory leaks:

useEffect(() => {
  const timer = setInterval(() => {}, 1000);
  return () => clearInterval(timer); // Cleanup
}, []);

Ref vs State: Use useRef for values that don’t trigger re-renders (DOM elements, mutable values). Use useState for values that should trigger UI updates.

Batching updates: React batches multiple setState calls in event handlers. In async code (setTimeout, promises), use flushSync for immediate updates (rare cases).

Children prop patterns: When passing children, use React.ReactNode type. For render props, use function children: {(data) => <Component data={data} />}.

Advanced Architecture Patterns

⚠️ Read This First: Most React projects do NOT need advanced architecture patterns. Apply only when:

1. AGENTS.md explicitly specifies architecture requirements
2. Codebase already uses domain/, application/, infrastructure/ folders
3. User explicitly requests architectural patterns

If none apply → Skip this section, use React best practices above.

Quick Context Verification

# Check AGENTS.md
cat agents/your-project/AGENTS.md | grep -i "architecture\|solid\|clean\|ddd"

# Check codebase structure
ls src/domain src/application src/infrastructure

• AGENTS.md mentions patterns OR folders exist OR user requests → Apply patterns
• None of above → Use standard React patterns only

Applicable Patterns

• SRP: Separate data fetching, logic, presentation (one responsibility per component/hook)
• DIP: Abstract services (use Context API or hooks, not direct imports)
• Result Pattern: Type-safe async error handling
• Clean Architecture: Layer separation when business logic is complex

For Complete Guide

MUST read architecture-patterns/references/frontend-integration.md for:

• Complete React examples with Clean Architecture
• SRP for components and hooks
• DIP with Context API
• Result Pattern in hooks
• Layer separation (domain/, application/, infrastructure/, presentation/)
• When to apply and when to stop

Also see: architecture-patterns/SKILL.md for Decision Tree and pattern selection.

References

• https://react.dev/
• https://react.dev/reference/react