@pixotope/react-context-store

A factory for React context-based state stores, with selector hooks, typed actions, and useSyncExternalStore under the hood.

Install

pnpm add @pixotope/react-context-store

This package depends on @pixotope/utils internally (for shallow-equality comparisons). As a workspace dependency it is resolved automatically — no extra install step is needed.

Quick start

import { createContextStore, ActionablePayload } from "@pixotope/react-context-store";

const initialState = {
  count: 0,
  user: { name: "John", age: 20 },
};

// Create a store with its initial state and a map of named actions.
const store = createContextStore(initialState, {
  increment: ({ set, get }) => {
    set({ ...get(), count: get().count + 1 });
  },
  incrementBy: ({ set, get }, action: ActionablePayload<number>) => {
    set({ ...get(), count: get().count + action.payload });
  },
});

function Counter() {
  // Select only the state this component needs; it only re-renders when
  // the selected value changes.
  const { state: count } = store.useStore((state) => state.count);
  const { increment, incrementBy } = store.useActions();

  return (
    <div>
      <p>{count}</p>
      <button onClick={() => increment()}>+1</button>
      <button onClick={() => incrementBy(5)}>+5</button>
    </div>
  );
}

function App() {
  // Wrap any component tree that uses the store's hooks in its Provider.
  return (
    <store.Provider>
      <Counter />
    </store.Provider>
  );
}

API overview

• createContextStore(initialState, actions?, options?) — Factory function that creates a store, returning the object described below.
• Provider — React component that wraps a component tree and gives it access to the store.
• useStore(selector?, compare?) — Hook that reads (a selection of) the store state, re-rendering the component when the selected state changes.
• useActions() — Hook that returns the actions passed to createContextStore, bound to the current store.
• useSetStore() — Hook that returns a function to update the store state without subscribing to updates.
• subscribe(selector, callback, compare?) / unsubscribe(callback) — Subscribe to store updates from outside the React component tree.
• ActionablePayload<Payload> — Type used on an action's second parameter to give it a typed payload argument (see incrementBy above).
• ContextOptions — Options passed as the third argument to createContextStore (global, compare).

See the generated API reference (pnpm typedoc) for full type signatures.