React

React Engineering & Performance Best Practices

Overview

Enforces declarative, component-driven UI architecture with optimal re-render cycles, state colocation, responsive optimistic updates, and robust accessibility standards.

When to Use

Activate whenever creating, refactoring, or optimizing React functional components, custom hooks, context providers, or UI interaction states.

Negative Constraints (What NOT to Do)

1. NEVER use useEffect to synchronize or compute derived state: Calculate derived state inline during render. Use useMemo only for computationally intensive derivations.
2. NEVER use array indices as key props on dynamic or reorderable lists: Always use stable, unique entity identifiers (item.id).
3. NEVER mutate React state directly: Always return new immutable references ([...prev, newItem] or { ...prev, key: value }).
4. NEVER declare subcomponents inside the render body of parent components: Declare components at module scope or in dedicated files to prevent DOM node remounting and lost focus state.
5. NEVER create memory leaks in useEffect: Always provide clean-up functions for event listeners, AbortController, timers, and websocket subscriptions.
6. NEVER lift state higher than necessary: Colocate state to the nearest common ancestor or leaf component to prevent wasteful re-renders of unrelated subtrees.

Rules & Patterns

1. State Colocation & Re-render Optimization

• State Colocation: Keep state as close as possible to the components that consume it.
• Composition to Prevent Re-renders: Pass expensive static subtrees as children to wrapper components holding state so the children do not re-render when the wrapper updates.

export function ExpandableCard({ title, children }: { title: string; children: React.ReactNode }) {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div className="rounded-xl border p-4">
      <button 
        type="button"
        onClick={() => setIsOpen(v => !v)}
        className="flex w-full justify-between font-semibold"
        aria-expanded={isOpen}
      >
        <span>{title}</span>
        <span>{isOpen ? '−' : '+'}</span>
      </button>
      {isOpen && <div className="mt-3 pt-3 border-t">{children}</div>}
    </div>
  );
}