React Guidelines

1. General Principles

• Component Composition: Build small, focused components and compose them to build complex UIs.
• Unidirectional Data Flow: Data flows down (props), actions flow up (callbacks).
• Immutability: Treat state as immutable. Use functional updates and immutable patterns.
• Colocation: Keep related logic, styles, and tests close to the component.

2. TypeScript Integration

• Strict Typing: Always use

  strict: true

  in

  tsconfig.json

  . avoiding

  any

  ensures type safety.
• Props Interfaces: Define explicit interfaces for component props.
  tsx

  interface ButtonProps {
      label: string;
      onClick: () => void;
      variant?: 'primary' | 'secondary';
  }

• Discriminated Unions: Use discriminated unions for state that can be in distinct modes (e.g., handling loading/success/error states).
  tsx

  type State = 
      | { status: 'idle' }
      | { status: 'loading' }
      | { status: 'success'; data: User }
      | { status: 'error'; error: Error };

• Event Types: Use React's built-in event types (e.g.,

  React.ChangeEvent<HTMLInputElement>

  ,

  React.FormEvent

  ).

3. State Management Best Practices

Derived State (Crucial)

• Avoid Redundant State: Do not store state that can be calculated from existing props or other state.
• Calculate on Render: Compute values directly in the component body.
  • Bad:
    tsx

    const [filteredList, setFilteredList] = useState([]);
    
    // This is an anti-pattern: syncing state
    useEffect(() => {
        setFilteredList(items.filter(i => i.active));
    }, [items]);

  • Good:
    tsx

    // Calculated during render. Always fresh, no sync bugs.
    const filteredList = items.filter(i => i.active); 

• Memoization: Use

  useMemo

  only if the calculation is computationally expensive.

useState vs useReducer

• Use

  useState

  for simple, independent values.
• Use

  useReducer

  for complex state logic, or when the next state depends on the previous one in complex ways.

4. useEffect Usage and Pitfalls

• Synchronization, Not Data Flow:

  useEffect

  is for synchronizing with external systems (APIs, DOM, subscriptions). It is not for transforming data or "watching" props to update state.
• Fetching Data: When fetching data, handle race conditions (e.g., ignore results if the component unmounts or the query changes).
• Strict Dependencies: Always include all variables used in the effect in the dependency array.
• Cleanup Functions: Always return a cleanup function for effects that create subscriptions or event listeners.

5. Component Patterns

• Custom Hooks: Extract logic into custom hooks (

  useUser

  ,

  useWindowSize

  ). This keeps components focused on UI.
• Container/Presentational: While strictly rigidly separating them is less common now, separating logically complex data-fetching components from pure UI components is still good practice.
• Fragments: Use

  <>

  (Fragments) to avoid unnecessary DOM wrapper nodes.

6. Performance

• Stable Identity: Wrap functions passed as props in

  useCallback

  only if the child component is wrapped in

  React.memo

  or if the function is a dependency of minimal effect.
• Lists: Always use a unique, stable

  key

  for list items. Do not use array index.
• Lazy Loading: Use

  React.lazy

  and

  Suspense

  for route-level code splitting.