Choosing MobX Side‑Effect Primitives and Batching Mutations in React

Decision: Which MobX Side‑Effect Primitive Fits Your Use Case?

\n

When a React component needs to react to observable changes you have three built‑in primitives: autorun, reaction, and when. The choice depends on whether the effect must run immediately, only on data changes, or once when a condition becomes true. In addition, runInAction lets you batch multiple mutations so observers see a single atomic update.

\n\n

Constraints to Consider

\n

\n
• Immediate execution – autorun fires on definition; reaction and when do not.
\n
• Data‑driven vs. predicate‑driven – reaction watches a derived value; when watches a boolean predicate.
\n
• Lifecycle – when disposes itself after the first true evaluation; the others require manual disposal.
\n
• Batching need – If you update several observables in one event handler, wrap them in runInAction to avoid intermediate notifications.
\n

\n\n

Compact Comparison

\n\n\n\n\n\n\n\n\n\n\n

Primitive	Runs on definition	Trigger	Auto‑dispose	Typical Use
autorun	Yes	Any observable read inside the function	No	Logging, persistence, UI sync that must reflect current state instantly
reaction	No	Change of the data function’s return value	No	Derived computations, API calls that should skip the initial value
when	No	Predicate becomes true	Yes (after first true)	Waiting for a loading flag, one‑time initialization
runInAction	N/A (batching helper)	N/A	N/A	Grouping multiple mutations into a single transaction

\n\n

Trade‑offs

\n

Autorun

\n

Pros: simplest API, guarantees the effect runs whenever any accessed observable changes. Cons: the immediate first run can cause duplicate side‑effects (e.g., writing to localStorage on mount when the value is already correct).

\n

Reaction

\n

Pros: separates the what to watch (data function) from the what to do (effect), skipping the initial evaluation. Cons: you must ensure the data function is pure and returns a stable reference; otherwise the effect may fire unexpectedly.

\n

When

\n

Pros: ideal for one‑shot await‑like patterns; auto‑disposes, reducing leak risk. Cons: if the predicate never becomes true the disposer stays alive—always keep a reference or clean up in a useEffect return.

\n

runInAction

\n

Pros: guarantees atomic visibility of all mutations; reduces reaction overhead. Cons: only batches synchronous code; asynchronous continuations need their own runInAction calls.

\n\n

Concrete Implementation in a React Component

\n

Assume a MobX 6 store using makeAutoObservable and React 18 with mobx-react-lite.

\n

// store.ts\nimport { makeAutoObservable, runInAction } from 'mobx';\n\nexport class TodoStore {\n  todos: string[] = [];\n  loading = false;\n  filter = 'all';\n\n  constructor() {\n    makeAutoObservable(this);\n  }\n\n  async fetchTodos() {\n    this.loading = true;\n    const data = await fetch('/api/todos').then(r => r.json());\n    runInAction(() => {\n      this.todos = data;\n      this.loading = false;\n    });\n  }\n\n  addTodo(text: string) {\n    runInAction(() => {\n      this.todos.push(text);\n      this.filter = 'all';\n    });\n  }\n}\n\nexport const store = new TodoStore();\n

\n\n

Using the primitives

\n

// TodoList.tsx\nimport { observer } from 'mobx-react-lite';\nimport { autorun, reaction, when } from 'mobx';\nimport { store } from './store';\nimport { useEffect } from 'react';\n\nconst TodoList = observer(() => {\n  // 1. Persist filter changes immediately\n  useEffect(() => {\n    const dispose = autorun(() => {\n      localStorage.setItem('filter', store.filter);\n    });\n    return dispose;\n  }, []);\n\n  // 2. Fetch suggestions only when filter changes (skip initial)\n  useEffect(() => {\n    const dispose = reaction(\n      () => store.filter,\n      (currentFilter) => {\n        if (currentFilter !== 'all') {\n          fetch(`/api/suggestions?filter=${currentFilter}`);\n        }\n      }\n    );\n    return dispose;\n  }, []);\n\n  // 3. Show a toast once loading finishes\n  useEffect(() => {\n    const dispose = when(\n      () => !store.loading,\n      () => alert('Todos loaded!')\n    );\n    return dispose; // safe even if predicate already true\n  }, []);\n\n  return (\n    \n       store.filter = e.target.value}\n      >\n        \n        \n        \n      \n       store.fetchTodos()} disabled={store.loading}>\n        {store.loading ? 'Loading…' : 'Reload'}\n      \n      
\n        {store.todos.map((t, i) => 
{t}
)}\n      
\n    \n  );\n});\n\nexport default TodoList;\n

\n\n

Validation Steps (Run in Project Root)

\n

\n
1. Install dependencies: npm install mobx mobx-react-lite (requires Node ≥ 18, write permission to node_modules).
\n
2. Add a test file side-effects.test.ts that creates a store instance, attaches each primitive, mutates observables, and asserts call counts using jest.fn() spies.
\n
3. Run the test suite: npm test -- --testPathPattern=side-effects.test.ts. Expected checks:\n
   \n
   • autorun spy called on mount and after each relevant mutation.
   \n
   • reaction spy called only after the data function’s return value changes, not on mount.
   \n
   • when spy called exactly once when loading flips to false; subsequent changes do not invoke it.
   \n
   • Two mutations wrapped in runInAction produce a single reaction notification; separate mutations produce two.
   \n
   \n
\n
4. Observe console output: the autorun log appears immediately, the reaction log appears only after filter change, the toast appears once after load.
\n

\n

Risks: Running tests mutates global MobX state; ensure each test disposes its reactions in afterEach. The when disposer becomes inert after firing—calling it again is a no‑op but should not be relied upon for cleanup.

\n\n

Limitations & Practical Checks

\n

\n
• autorun cannot be delayed; if you need to skip the first run, switch to reaction with a data function that returns the current value.
\n
• reaction’s data function must be deterministic; returning a new object each time will trigger the effect on every evaluation.
\n
• when only works for predicates that eventually become true; for long‑lived conditions consider a regular reaction with a guard.
\n
• runInAction does not batch across await boundaries—wrap each async continuation separately.
\n
• Verify behavior in development by enabling mobx.setGlobalConfig({ enforceActions: 'always' }) and confirming no “Side effect” warnings appear.
\n

\n\n

How to Confirm the Result in Production

\n

Add a lightweight telemetry hook that increments a counter each time a reaction fires. In the browser console, after a user interaction, the counter should match the expected number of batched updates (e.g., 1 for a batched addTodo, 2 for two separate filter changes). This runtime check validates that the chosen primitives and batching behave as designed without relying on test‑only mocks.

\n\n

Summary

\n

Pick autorun for always‑on side‑effects, reaction when you need to skip the initial run and watch a derived value, and when for one‑time await‑style conditions. Wrap any multi‑property mutation in runInAction to keep observers in sync. The table, trade‑off notes, and the React example above give a decision framework you can apply directly to a MobX 6 / React 18 codebase.