Atomic Batch Updates with setMultiple in NexusStore

Every time you call setState on a NexusStore store, the store notifies all its subscribers and React schedules a re-render for any component that reads the updated key. Calling setState twice in a row on the same store therefore triggers two separate notification cycles — potentially two render passes — even though both updates are logically a single operation. setMultiple solves this by batching all changes into one atomic update: the store notifies listeners exactly once, and React renders exactly once.

The Problem with Multiple `setState` Calls

❌ Two setState calls — two render cycles

store.setState(
  (keys) => keys.auth,
  (draft) => {
    draft.isLoggedin = false;
  },
);
store.setState(
  (keys) => keys.theme,
  (draft) => {
    draft.mode = "light";
  },
);

✅ One setMultiple call — one render cycle

store.setMultiple((draft) => {
  draft.auth.isLoggedin = false;
  draft.theme.mode = "light";
  draft.theme.color = "#ffffff";
});

The second snippet produces the same final state but triggers a single notification, keeping your component tree stable.

Three Update Patterns

Immer draft (simplest)
Plain object merge
Functional update (non-Immer)

When your store is wrapped with immer(), pass a draft mutator function directly to setMultiple. The entire store’s current state arrives as a mutable draft — assign to any keys you want to change and leave the rest untouched.The SetMultiple component in the demo app demonstrates this pattern:

src/components/SetMultiple.jsx

import { useSelector } from "../store/hooks";
import { store } from "../store/store";

export default function SetMultiple() {
  const auth = useSelector((state) => state.auth);
  const theme = useSelector((state) => state.theme);

  function handleAuthAndTheme() {
    store.setMultiple((draft) => {
      draft.auth.isLoggedin = false;
      draft.theme.mode = "light";
      draft.theme.color = "#ffffff";
    });
  }

  return (
    <fieldset>
      <legend>Cart</legend>
      <p>Auth: {auth.isLoggedin ? "Logged In" : "Logged Out"}</p>
      <p style={{ border: `1px solid ${theme.color}` }}>
        Theme: {theme.mode}
      </p>
      <button onClick={handleAuthAndTheme}>Set Multiple</button>
    </fieldset>
  );
}

To inspect draft values in the console, use current(draft) from the immer package. Logging the proxy directly produces an unreadable output.

Pass a plain object to setMultiple when you have static values that don’t depend on current state. NexusStore shallowly merges the object into the store — any key you omit stays exactly as it was.

Plain object — keys are shallow-merged

store.setMultiple({
  auth: {
    isLoggedin: false,
  },
  theme: {
    mode: "light",
    color: "#ffffff",
  },
});

In this example, cart and settings are not mentioned, so they remain in the store unchanged. Only auth and theme are overwritten with the values provided.

When your store is not Immer-wrapped but you still need to derive the next state from the current one, pass a function that receives the full current state and returns a partial update object. NexusStore merges the returned object automatically — there is no need to spread ...state yourself.

Functional update — receives current state, returns partial object

store.setMultiple((state) => ({
  auth: {
    isLoggedin: !state.auth.isLoggedin,
  },
  theme: {
    mode: "light",
    color: "#ffffff",
  },
}));

Because NexusStore performs the merge, omitting cart and settings from the returned object does not remove them from the store.

Replacing the Entire Store with `replaceStore`

By default setMultiple merges. Pass true as the second argument to replace the store entirely — the object you provide (or return from your function) becomes the complete new state.

replaceStore: true — the returned object is the new store

store.setMultiple(
  {
    auth: { isLoggedin: false },
    theme: { mode: "light", color: "#ffffff" },
  },
  true,
);

The Immer + replaceStore pattern lets you read current values from the draft while returning a fresh object:

Immer draft + replaceStore — read draft, return new object

store.setMultiple(
  (draft) => ({
    auth: { isLoggedin: !draft.auth.isLoggedin },
    theme: { mode: "light", color: "#ffffff" },
  }),
  true,
);

When replaceStore is true, any key you omit from the returned object is permanently removed from the store. Every top-level key that should survive the update must be explicitly included. If you spread ...state inside a replaceStore call, all existing keys are preserved, which defeats the purpose of the replace flag.

When to Use Each API

setState

Updating a single top-level key in the store. Works for both primitive values and nested objects (with or without Immer).

setMultiple

Updating two or more keys in the same store at once. Emits a single notification — one render cycle regardless of how many keys change.

Separate setState calls

Updating keys that live in different stores. setMultiple only operates within one store, so you must call each store’s setState individually.

Scenario	Recommended approach
Toggle a boolean	`setState` with a direct value or functional update
Update nested object/array	`setState` with an Immer draft function
Log out and reset theme at once	`setMultiple` on a shared store
Reset entire store to defaults	`setMultiple` with `replaceStore: true`
Update `authStore` and `themeStore` together	Separate `setState` on each store

Get Started

Core Concepts

Advanced

Atomic Batch Updates with setMultiple in NexusStore

The Problem with Multiple `setState` Calls

Three Update Patterns

Replacing the Entire Store with `replaceStore`

When to Use Each API

setState

setMultiple

Separate setState calls

Build docs developers (and LLMs) love

Get Started

Core Concepts

Advanced

Documentation Index

​The Problem with Multiple setState Calls

​Three Update Patterns

​Replacing the Entire Store with replaceStore

​When to Use Each API

setState

setMultiple

Separate setState calls

Build docs developers (and LLMs) love

The Problem with Multiple `setState` Calls

Three Update Patterns

Replacing the Entire Store with `replaceStore`

When to Use Each API