React Effect Decision

React effect decision

Default rule for this project: do not reach for direct useEffect first.

Most effect usage in React code is a sign that the component is syncing state that should be derived during render, routing an event through state, or resetting local state in a way React already models better.

This skill merges:

• React's official decision tree from "You Might Not Need an Effect"
• The project's stricter no direct useEffect preference

Start here

Before writing any effect, ask these in order:

1. Can I calculate this from props or state during render
2. Is this triggered by a user action and better placed in the event handler
3. Am I trying to reset component state when identity changed and should use key
4. Is this an expensive pure calculation that should use useMemo
5. Is this an external subscription that should use useSyncExternalStore or a focused custom hook
6. Is this real external synchronization that must happen on mount or on dependency changes

If you answer yes to any of 1 through 5, do not write a direct useEffect.

Project stance

React allows effects for real external synchronization. This project is stricter:

• Avoid direct useEffect in components whenever a clearer pattern exists
• Prefer derived values, event handlers, key remounts, memoization, query libraries, Convex hooks, and focused custom hooks
• If mount only external setup is truly needed, use an explicit useMountEffect wrapper instead of sprinkling raw useEffect through feature code

Example wrapper:

import { useEffect } from "react";

export function useMountEffect(effect: () => void | (() => void)) {
  useEffect(effect, []);
}

Use that only for one time external setup like DOM focus, third party widgets, or browser API listeners that belong to the component lifecycle.

Decision guide

1. Derived state belongs in render

Bad smell:

• useEffect(() => setX(deriveFromY(y)), [y])
• State that only mirrors props or other state

Do this instead:

function TodoList({ todos, showActive }: Props) {
  const activeTodos = todos.filter((todo) => !todo.completed);
  const visibleTodos = showActive ? activeTodos : todos;

  return <List items={visibleTodos} />;
}

If it can be calculated from existing inputs, keep it out of state.

2. Expensive pure calculations use useMemo

If the calculation is pure and expensive, memoize it instead of syncing it into state:

const visibleTodos = useMemo(
  () => getVisibleTodos(todos, showActive),
  [todos, showActive],
);

Use memoization only when there is real repeated work to skip.

3. Event caused work belongs in the event handler

Bad smell:

• Set a flag in state
• Wait for an effect to notice the flag
• Reset the flag after the side effect runs

Do this instead:

function PurchaseButton({ product }: Props) {
  async function handleClick() {
    await addToCart(product);
    showNotification(`Added ${product.name}`);
  }

  return <button onClick={handleClick}>Buy</button>;
}

If the work happens because the user clicked, submitted, dragged, or selected, keep it in the handler.

4. Reset with key, not effect choreography

Bad smell:

• useEffect(() => setFormState(initialFromProps), [id])

Do this instead:

function EditContact({ contact, onSave }: Props) {
  return <EditContactForm key={contact.id} contact={contact} onSave={onSave} />;
}

If a different entity should feel like a fresh component instance, give the inner component a key.

5. Adjusting state from prop changes is a last resort

If you cannot derive it and do not want a full remount, adjust the state during render of the same component before children render stale data.

Prefer these, in order:

1. Derive it
2. Reset with key
3. Store an ID and derive the selected object from current inputs
4. Only then use a guarded render time adjustment pattern

6. Data fetching should use the app's data layer or a focused hook

Bad smell:

• Raw fetch(...).then(setState) inside a component effect
• Manual loading, retry, cancellation, and stale response handling in feature code

Preferred options:

• Use Convex React hooks where the data already lives in Convex
• Use the project's existing data abstraction or a query library for remote APIs
• If raw client fetching is unavoidable, isolate it inside a custom hook and handle stale response cleanup

Example custom hook pattern:

function useSearchResults(url: string) {
  const [data, setData] = useState<Result[] | null>(null);

  useEffect(() => {
    let ignore = false;

    fetch(url)
      .then((response) => response.json())
      .then((json) => {
        if (!ignore) {
          setData(json);
        }
      });

    return () => {
      ignore = true;
    };
  }, [url]);

  return data;
}

That is still less preferred than a dedicated query layer, but better than scattering raw fetch effects across components.