get-convex/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.

7. External subscriptions should use useSyncExternalStore

For browser or third party stores, prefer the React built in subscription model:

function useOnlineStatus() {
  return useSyncExternalStore(
    subscribe,
    () => navigator.onLine,
    () => true,
  );
}

This is clearer and safer than mirroring an external mutable source through ad hoc effect code.

8. True external synchronization is the narrow allowed case

An effect or useMountEffect is appropriate when the component must synchronize with something outside React:

• DOM focus or scroll positioning
• Third party widget setup and cleanup
• Browser API subscriptions
• Network synchronization that should happen because the component is on screen, not because a user event fired

When you use one, document the external system in a comment or nearby helper.

Quick smell test

If you are about to write useEffect, check:

• Is this just derived state
• Is this event specific logic
• Is this a reset that should use key
• Is this a pure expensive calculation
• Is this a subscription better modeled with useSyncExternalStore
• Is this data loading that belongs in Convex, a query library, or a custom hook
• What external system am I synchronizing with

If you cannot name the external system, you probably do not need an effect.

Code review prompts

Use these during review:

• What breaks if this effect is removed and the value is derived during render
• Is this component storing data that can be recomputed from props or state
• Why is this work not in the click, submit, or change handler that caused it
• Would key={entityId} remove the reset logic entirely
• Should this be a custom hook instead of inline effect code
• Is this component talking to an external system, or only to React state

Summary

The safest path in this repo is simple:

• Derive during render when possible
• Handle user caused work in handlers
• Reset with key
• Memoize expensive pure work
• Use dedicated hooks for fetching and subscriptions
• Reserve effect style lifecycle code for real external synchronization

Sources:

• React docs: You Might Not Need an Effect