Preventing React Hook Infinite Loops

Use when: Array/object content should trigger effect, not reference change.

Problem:

// ❌ WRONG - assets array recreated every render = infinite loop
const [result, setResult] = useState(null);
useEffect(() => {
  processAssets(assets).then(setResult);
}, [assets]); // Reference changes every render!

Solution:

// ✅ RIGHT - stable string key only changes when content changes
const assetsKey = useMemo(
  () =>
    assets
      .map((a) => a.id)
      .sort()
      .join(","),
  [assets]
);

useEffect(() => {
  processAssets(assets).then(setResult);
}, [assetsKey]); // String comparison, stable reference

When to use: Entity arrays with stable IDs (assets, users, products).

Pattern 2: Ref for Mutable Values

Use when: Need latest callback value without triggering re-render.

Problem:

// ❌ WRONG - callback in dependency causes loop
const handleUpdate = useCallback(() => {
  onUpdate(data);
}, [onUpdate, data]); // onUpdate might be unstable

Solution:

// ✅ RIGHT - ref holds latest without triggering re-render
const onUpdateRef = useRef(onUpdate);
onUpdateRef.current = onUpdate;

const handleUpdate = useCallback(() => {
  onUpdateRef.current(data);
}, [data]); // Only data in deps

When to use: Callbacks from props, event handlers passed from parent.

Pattern 3: Object Comparison with JSON

Use when: Config object should trigger effect on value change.

// For config objects that should trigger on value change
const configKey = useMemo(() => JSON.stringify(config), [config]);

useEffect(() => {
  applyConfig(config);
}, [configKey]);

⚠️ Limitations: Only works for JSON-serializable objects (no functions, undefined, circular refs).

Pattern 4: Stable Callbacks from Props

Use when: Parent passes callbacks that may not be memoized.

// When parent passes unstable callbacks
const stableOnChange = useCallback(
  (value: T) => onChange?.(value),
  [] // Empty deps - uses closure
);

// Access latest onChange via ref if needed
const onChangeRef = useRef(onChange);
useLayoutEffect(() => {
  onChangeRef.current = onChange;
});

When to use: Creating reusable components that accept callback props.

Anti-Patterns Detection

See: Anti-Patterns Reference for detection strategies and automated linting rules.

Debugging Workflow

When infinite loop occurs:

1. Confirm loop: Add console.log at start of useEffect

2. Identify culprit: Log each dependency with reference identity

   useEffect(() => {
     console.log("Effect running", { dep1, dep2, dep3 });
   }, [dep1, dep2, dep3]);
   

3. Check reference stability: Which dep has different reference each log?

4. Apply pattern: Use appropriate pattern from Core Patterns above

5. Verify fix: Remove logs, confirm loop stopped

See: Debugging Guide for React DevTools profiling and advanced techniques.

Chariot Codebase Examples

Example 1: Cluster Detection

Location: modules/chariot/ui/src/components/nodeGraph/hooks/useClusterManagement.ts

Pattern Used: Serialized dependency key

const serializedAssets = useMemo(
  () =>
    assets
      .map((a) => a.id)
      .sort()
      .join(","),
  [assets]
);

useEffect(() => {
  detectClusters(assets);
}, [serializedAssets]); // Prevents re-clustering on every render

Example 2: Camera Event Handlers

Location: modules/chariot/ui/src/components/nodeGraph/hooks/useViewportCulling.ts

Pattern Used: Ref for callback stability

const debounceTimerRef = useRef<NodeJS.Timeout>();

const handleCameraMove = useCallback(() => {
  // Uses ref to avoid callback dependencies
}, []); // Empty deps, stable across renders

See: Chariot Examples for complete implementations with context.

Integration

Called By

• frontend-developer agent - When implementing React hooks
• frontend-reviewer agent - During code review for performance
• frontend-security agent - When reviewing client-side rendering logic

Requires (invoke before starting)

Calls (during execution)

None - terminal skill (provides patterns, doesn't orchestrate other skills)

Pairs With (conditional)

Library Integration

React Query / TanStack Query

Query keys follow same serialization pattern:

const queryKey = useMemo(
  () => ["assets", filters.status, filters.class],
  [filters.status, filters.class] // Only stable values
);

Zustand / Redux

Selector stability:

const stableSelector = useCallback(
  (state) => state.assets.filter((a) => a.status === status),
  [status] // Only status, not filter function
);

React Hook Form

Watch dependencies:

const watchedFields = useWatch({ control, name: ["field1", "field2"] });
const fieldKey = useMemo(() => JSON.stringify(watchedFields), [watchedFields]);

Related Skills

• optimizing-react-performance - Broader performance patterns (memoization, virtualization)
• debugging-systematically - When tracking down the loop source (root cause analysis)
• adhering-to-dry - Extract reusable serialization utilities
• testing-react-hooks - Testing patterns for custom hooks with complex dependencies

Advanced Topics

For advanced patterns and edge cases, see:

• Advanced Patterns - Deep comparison hooks, multi-level serialization
• Performance Tradeoffs - When serialization costs more than re-render
• ESLint Configuration - Automated detection with exhaustive-deps rule
• TypeScript Patterns - Type-safe dependency serialization

Key Principles

1. Reference vs Value: React compares by reference; objects/arrays need serialization
2. Serialization over Deep Compare: JSON.stringify or key-based > deep equality checks
3. Refs for Latest Values: Use refs when you need current value without re-render trigger
4. Empty Deps + Refs: Prefer empty dependency array with refs over unstable dependencies
5. Test in Development: Infinite loops are easier to catch with React StrictMode enabled

Success Criteria

✅ No "Maximum update depth exceeded" errors ✅ useEffect runs only when logical dependencies change ✅ Browser profiler shows no excessive re-renders ✅ ESLint exhaustive-deps rule passes with no suppressions ✅ Custom hooks work correctly when parent re-renders