React Agent

Pragmatic React development that prioritizes simplicity, maintainable state management, and optimal rendering performance.

Core Principles

1. Start Simple, Add Complexity Only When Needed

Default approach:

• Use local state (useState ) first

• Lift state up when components need to share

• Add Context only when prop drilling becomes painful (>3 levels)

• Consider external state management (Zustand/Redux) only for truly global state

Red flags of over-engineering:

• Creating abstractions before they're needed

• Adding state management libraries for 2-3 shared values

• Implementing complex patterns for simple forms

• Premature optimization without measuring

2. State Management Decision Tree

Follow this decision tree when choosing state solutions:

Is this state used in only one component? ├─ YES → useState └─ NO → Is it shared by 2-3 closely related components? ├─ YES → Lift state to nearest common parent └─ NO → Does it need to be accessed across distant components? ├─ YES → Is it truly global (auth, theme, i18n)? │ ├─ YES → Context API or Zustand │ └─ NO → Still use props/composition when possible └─ NO → Re-evaluate component structure

Quick reference:

• 1 component → useState

• 2-3 related → Lift state + props

• Many components (same branch) → Context API

• App-wide global → Zustand (recommended) or Redux Toolkit

• Server data → TanStack Query or SWR

3. Rendering Optimization Rules

Only optimize when:

• Profiler shows actual performance issue

• Component re-renders are visibly slow

• Working with large lists (>100 items)

• Expensive computations are occurring

Optimization toolkit:

• React.memo

• for expensive components that receive same props

• useMemo

• for expensive calculations

• useCallback

• when passing callbacks to memoized children

• useTransition

• for non-urgent updates (React 18+)

Don't optimize prematurely:

• Avoid wrapping everything in memo by default

• Don't use useMemo for simple calculations

• Don't optimize before measuring

Quick Start Workflow

1. Analyze Requirements

// Ask yourself: // - What data do I need? (local vs shared) // - How many components need this data? // - Is this data from server or client? // - Are there performance concerns?

2. Choose State Pattern

See references/state-patterns.md for detailed patterns and examples.

Local State Example:

function Counter() { const [count, setCount] = useState(0); return <button onClick={() => setCount(c => c + 1)}>{count}</button>; }

Lifted State Example:

function Parent() { const [items, setItems] = useState([]); return ( <> <ItemList items={items} /> <ItemForm onAdd={(item) => setItems([...items, item])} /> </> ); }

3. Implement with TypeScript

// Always type props and state interface Props { userId: string; onUpdate: (data: UserData) => void; }

function UserProfile({ userId, onUpdate }: Props) { const [isLoading, setIsLoading] = useState(false); // implementation }

4. Add Optimization (Only If Needed)

// Measure first with React DevTools Profiler // Then optimize specific bottlenecks

const MemoizedList = memo(ExpensiveList);

const handleClick = useCallback(() => { // Only when passing to memoized children }, [dependencies]);

const expensiveValue = useMemo(() => { // Only for truly expensive calculations return heavyComputation(data); }, [data]);

Common Patterns

Pattern 1: Form Handling

Simple form (controlled):

function SimpleForm() { const [email, setEmail] = useState('');

const handleSubmit = (e: FormEvent) => { e.preventDefault(); // handle submission };

return ( <form onSubmit={handleSubmit}> <input value={email} onChange={(e) => setEmail(e.target.value)} /> </form> ); }

Complex form: Use React Hook Form or Formik (only for 5+ fields)

Pattern 2: Data Fetching

// Prefer TanStack Query for server state import { useQuery } from '@tanstack/react-query';

function UserProfile({ userId }: Props) { const { data, isLoading, error } = useQuery({ queryKey: ['user', userId], queryFn: () => fetchUser(userId), });

if (isLoading) return <Spinner />; if (error) return <Error error={error} />; return <div>{data.name}</div>; }

Pattern 3: Conditional Rendering

// Simple ternary {isLoading ? <Spinner /> : <Content />}

// Multiple conditions - extract to variable const content = (() => { if (isLoading) return <Spinner />; if (error) return <Error />; if (!data) return <Empty />; return <Content data={data} />; })();

Performance Checklist

Before optimizing, verify with React DevTools Profiler:

• Identify which components re-render

• Measure render time

• Check why re-renders happen (props/state/context)

Quick wins:

• Extract expensive operations outside component

• Use proper key props for lists (not index unless static)

• Split large components into smaller ones

• Use Code Splitting for large bundles (React.lazy )

For lists:

// Virtualization for 100+ items import { useVirtualizer } from '@tanstack/react-virtual';

// Key requirement: stable, unique IDs {items.map(item => ( <Item key={item.id} {...item} /> ))}

Anti-Patterns to Avoid

❌ Over-abstraction:

// Don't create generic wrappers unnecessarily <GenericForm config={complexConfig} />

❌ Premature memoization:

// Don't wrap everything by default export default memo(SimpleButton); // unnecessary

❌ Prop drilling Context:

// Don't use Context just to avoid 2 levels of props <Context.Provider value={simpleValue}>

❌ Mutations:

// Never mutate state items.push(newItem); // Wrong setItems([...items, newItem]); // Correct

References

Load these references for deeper guidance:

• State Management → references/state-patterns.md

• Detailed patterns with examples

• Performance → references/performance-guide.md

• Optimization techniques and profiling

• TypeScript → references/typescript-patterns.md

• Type patterns and utilities

• Hooks → references/hooks-guide.md

• Custom hooks and patterns

• Testing → references/testing-guide.md

• Testing with React Testing Library

Key Constraints

MUST DO:

• Type all props and state with TypeScript

• Use stable keys for lists (not array index for dynamic lists)

• Clean up effects (return cleanup function)

• Handle loading and error states

• Validate before optimizing (use Profiler)

MUST NOT:

• Mutate state or props

• Use index as key for dynamic lists

• Create functions inside JSX

• Forget useEffect cleanup (memory leaks)

• Over-engineer simple solutions

• Optimize without measuring