Stoic

Stoic is a small state management library for React, built on useSyncExternalStore. You define state and actions much like you would with any store library, but Stoic also lets you declare derived state — values computed from other state — as part of the store itself.

The key difference from most state managers: Stoic tracks the relationships between your state automatically. When something changes, only the derived values that actually depend on it are recomputed, and only the components reading those values rerender. There are no dependency arrays to maintain.

• ⚡️ Plain function actions — no dispatch, no action types
• 🧠 Reactive derived state with automatic dependency tracking
• 🚀 First-class async actions, with built-in pending/error status and AbortSignal cancellation
• 🔌 A small plugin system (persist and devtools are included; write your own for the rest)
• 💙 Fully typed, with state and action arguments inferred by your editor

Installation

npm install stoic-store

Requires React 18+. Published as ESM only. See Installation.

Usage

import { createStore } from "stoic-store";

type State = { items: CartItem[]; tax: number };
type Derived = { subtotal: number; total: number };

export const cart = createStore<State, Derived>({
  state: {
    items: [{ id: 1, title: "Keyboard", price: 100 }],
    tax: 0.2,
  },

  derived: {
    subtotal: ({ items }) => items.reduce((sum, item) => sum + item.price, 0),
    total: ({ subtotal, tax }) => subtotal * (1 + tax),
  },
});

export const { addItem } = cart.actions({
  addItem: ({ set }, item: CartItem) => {
    set((s) => ({ items: [...s.items, item] }));
  },
});

Read it in a component — it only rerenders when total changes:

import { useStore } from "stoic-store/react";

function CartSummary() {
  const total = useStore(cart, (state) => state.total);

  return <h2>Total: ${total}</h2>;
}

And update it by calling the action like a regular function:

addItem({ id: 2, title: "Mouse", price: 50 });

subtotal and total recompute automatically whenever items or tax change — you never write that logic yourself.

Why Stoic

Most React state managers give you a store and leave computed values to you — so subtotal ends up as a useMemo in one component, a selector in another, and a hand-maintained dependency array in both. Stoic's premise is that a value computed from state belongs in the store, declared once, with the dependency graph worked out for you.

That's the whole pitch: one store object, plain-function actions, and declared derived state with automatic dependency tracking — in 2.4 kB gzipped, with no runtime dependencies.

Stoic is a good fit if you have real computed state (totals, filtered lists, aggregate stats), you want it typed end to end, and you'd rather have one store per domain than a graph of atoms.

Reach for something else if you want the smallest possible store and don't need derived state (Zustand is smaller); you prefer bottom-up, atom-level granularity (Jotai); you want to mutate state directly (Valtio); or you need middleware and conventions of a large app framework (Redux Toolkit).

Two honest trade-offs, up front:

• Derived stores need their types spelled out — createStore<State, Derived>. This is a TypeScript limitation, not a temporary one; the reasoning is documented.
• Dependency tracking is per top-level key and compares by reference, so mutating state in place (state.items.push(x)) won't recompute anything. Replace, don't mutate.

Documentation

Full documentation lives in docs/.

| | | | --- | --- | | Getting started | Installation · Quick Start · Core Concepts | | Guides | Reading State · Actions · Derived State · Batching · Per-instance Stores · TypeScript · Testing | | Plugins | Overview · devtools · persist · Writing a plugin | | Reference | API Reference · FAQ · Versioning · Philosophy |

Runnable applications are in examples/: a shopping cart, a GitHub user search, and a kanban board. Run yarn build at the repository root first — they resolve Stoic from dist/.

Contributing

Issues, discussions, ideas, and pull requests are always welcome — open one on the issue tracker.

If you're sending a pull request, CONTRIBUTING.md covers setup, the commands, and what a change is expected to come with (tests, a changeset, and a benchmark if you touched a hot path).

If Stoic makes your React code simpler, consider giving the project a ⭐️ on GitHub.

License

MIT © peakercope