Quick look

The same counter — but no selector, no useShallow, and derived state that caches itself:

import { create, observer } from '@coaction/react';

const useCounter = create((set) => ({
  count: 0,
  step: 1,
  // cached automatically — recomputed only when `count` changes
  get doubled() {
    return this.count * 2;
  },
  increment() {
    set(() => {
      this.count += this.step; // mutable write, immutable result
    });
  }
}));

const Counter = observer(() => {
  const store = useCounter(); // tracks only the fields it actually reads

  return (
    <button onClick={store.increment}>
      {store.count} (step {store.step}) → {store.doubled}
    </button>
  );
});

import { create } from 'zustand';
import { useShallow } from 'zustand/react/shallow';
import { useMemo } from 'react';

const useCounter = create((set) => ({
  count: 0,
  step: 1,
  increment: () => set((s) => ({ count: s.count + s.step }))
}));

function Counter() {
  const { count, step } = useCounter(
    useShallow((s) => ({ count: s.count, step: s.step }))
  );
  const doubled = useMemo(() => count * 2, [count]);

  return (
    <button onClick={() => useCounter.getState().increment()}>
      {count} (step {step}) → {doubled}
    </button>
  );
}

Why Coaction

You don't need a worker, tabs, or CRDTs to benefit. Coaction folds the pieces you'd normally assemble by hand into one cohesive signal graph, so tracking, computed values, and the fields they read invalidate together:

• Automatic render tracking — observer() re-renders a component only for the fields it reads. No selectors, no useShallow.
• Cached computed by default — get value() getters memoize until a dependency changes. No useMemo, no reselect.
• Mutable writes, immutable results — just this.count += 1 inside set(). Powered by Mutative (~18x faster than Zustand + Immer in our benchmark).
• this + OOP-style actions — natural getters and actions; methods destructured from getState() stay bound.
• Escape hatches when you want them — useStore(selector), useStore.auto(), and get(deps, selector) keep explicit control available.

And when you need it, the same store scales up. Built on a transport + patch foundation, the same store source can run in a Worker, SharedWorker, across tabs, or in real-time collaboration — multithreading is the ceiling, not the entry fee. Adopt the single-threaded DX first, grow into shared mode when the architecture calls for it.

Install

For the core library without any framework:

For React applications:

npm install coaction @coaction/react

Works with React, Vue, Angular, Svelte, and Solid, plus adapters for Redux, Zustand, MobX, Pinia, Jotai, Valtio, and XState. See Integration for package names and docs.

Coaction or Zustand?

Coaction keeps a familiar Zustand-style create API but chooses a larger, batteries-included runtime. Zustand is the smaller, more battle-tested choice when selectors and middleware already cover the problem cleanly.

Reach for Coaction when:

• components are selector-heavy or lean on repeated derived state
• you want derived values cached by default, without useMemo/reselect
• you'd otherwise stack react-tracked + a computed plugin + auto-selectors and maintain it yourself
• Worker / multi-tab / collaboration is on your roadmap

Stick with Zustand when:

• you need a small hook store with a few selectors
• a near-zero-dependency core and bundle minimalism are top priorities
• your team prefers explicit, magic-free subscriptions

See the honest, detailed case in Why Coaction Without Multithreading and the full Coaction vs Zustand comparison.

Usage

Your first store

import { create, observer } from '@coaction/react';

const useStore = create((set) => ({
  count: 0,
  get doubleCount() {
    return this.count * 2; // cached until `count` changes
  },
  increment() {
    set(() => {
      this.count += 1;
    });
  }
}));

const Counter = observer(() => {
  const store = useStore();
  return (
    <div>
      <p>Count: {store.count}</p>
      <p>Double: {store.doubleCount}</p>
      <button onClick={store.increment}>Increment</button>
    </div>
  );
});

Wrap a component in observer() and it subscribes to exactly the fields it reads. Plain useStore() outside observer() stays a whole-store subscription — use useStore(selector) when you want the classic explicit style.

Writes happen inside set()

Coaction state is immutable by default. Getters and methods read through this, but writes must go through set():

incrementWrong() {
  this.count += 1; // ❌ throws — outside set()
}

increment() {
  set(() => {
    this.count += 1; // ✅ mutable draft, immutable result
  });
}

set() is the boundary where Coaction produces the next immutable state and notifies subscribers. When patches are enabled, it's also where patch pairs are generated — the same mechanism that powers shared mode later.

Derived state

Accessor getters are the default derived-state API and cache automatically:

import { create } from '@coaction/react';

type CartItem = { price: number; quantity: number };

const useCart = create((set) => ({
  items: [] as CartItem[],
  get total() {
    return this.items.reduce((sum, i) => sum + i.price * i.quantity, 0);
  },
  add(item: CartItem) {
    set(() => {
      this.items.push(item);
    });
  }
}));

When you want explicit dependencies, use the get(deps, selector) form:

import { create } from '@coaction/react';

type CartItem = { price: number; quantity: number };

const useCart = create((set, get) => ({
  items: [] as CartItem[],
  total: get(
    (state) => [state.items],
    (items) => items.reduce((sum, i) => sum + i.price * i.quantity, 0)
  )
}));

Escape hatches

Automatic tracking is the default, not a cage. The full explicit toolbox stays available:

import { createSelector } from '@coaction/react';

// selector across multiple stores; returns a hook
const useCartCredit = createSelector(useCart, useUser);
const selectors = useCart.auto();

function CartSummary() {
  // classic selector (familiar Zustand DX)
  const total = useCart((state) => state.total);

  // cached auto-selector map
  const total2 = useCart(selectors.total);

  // selector across multiple stores
  const remaining = useCartCredit((cart, user) => cart.total + user.credit);

  return <span>{total + total2 + remaining}</span>;
}

The explicit useStore(selector) path is version + recompute + Object.is — the same model Zustand uses. Coaction's fine-grained tracking lives in observer() and cached getters, so mix the styles freely.

Slices

Slices are a first-class store shape with namespace support:

const counter = (set) => ({
  count: 0,
  increment() {
    set(() => {
      this.count += 1; // `this` targets the slice
    });
  },
  incrementByStep() {
    set((draft) => {
      draft.counter.count += draft.settings.step; // root draft for cross-slice
    });
  }
});

const settings = (set) => ({
  step: 1,
  setStep(step) {
    set(() => {
      this.step = step;
    });
  }
});

const useStore = create({ counter, settings }, { sliceMode: 'slices' });

Methods destructured from getState() stay bound:

const { increment } = useStore.getState().counter;
increment(); // still works — `this` stays bound to the slice

Scaling up: shared mode

Everything above runs single-threaded. When your architecture calls for it, the same store source can move to a Worker, SharedWorker, or multiple tabs — no rewrite, no manual message passing.

counter.js

export const counter = (set) => ({
  count: 0,
  increment() {
    set(() => {
      this.count += 1;
    });
  }
});

worker.js

import { create } from '@coaction/react';
import { counter } from './counter';

create(counter);

App.jsx

import { create } from '@coaction/react';
import { counter } from './counter';

const worker = new Worker(new URL('./worker.js', import.meta.url), {
  type: 'module'
});
const useStore = create(counter, { worker });

In shared mode the worker owns the state (the main store); webpage threads are client mirrors that read local state and proxy method calls to the main store. Coaction handles sequencing, patch sync, and reconnect recovery for you.

TypeScript note: in a client context the store type is AsyncStore (methods become async, proxied to the worker); in the worker context it's a synchronous Store.

See the threading model for the full authority rules.

Reusable SharedWorker store

For multi-tab state, the same store module can create a SharedWorker on the webpage and run as the authority store inside the worker:

import { create } from 'coaction';

const worker = globalThis.SharedWorker
  ? new SharedWorker(new URL('./store.js', import.meta.url), { type: 'module' })
  : undefined;

export const store = create(
  (set) => ({
    count: 0,
    increment() {
      set(() => {
        this.count += 1;
      });
    }
  }),
  worker ? { worker } : undefined
);

See the reusable store example and the 3D multi-window scene for SharedWorker patterns.

Performance

Benchmark updating 50K arrays and 1K objects, higher is better (source):

Benchmark snapshot from the current scripts/benchmark.ts comparison.

Coaction performs on par with Zustand in standard usage. The gap appears with immutable helpers: Coaction with Mutative is ~18.3x faster than Zustand with Immer.

For the benchmark methodology and derived-state positioning, see Zustand-focused benchmarks.

Integration

Coaction works across frameworks, with adapters for popular state libraries and middleware.

For collaboration, see @coaction/yjs.

Support boundaries are documented, not implied. Slices mode is core-only; third-party state adapters bind the whole store. Not every feature works in every mode — see the support matrix for the exact, tested combinations.

Custom integrations should use defineExternalStoreAdapter() from coaction. See the adapter contract before writing one.

Examples

• 3D multi-window scene — SharedWorker state across multiple browser windows (demo video).
• Framework examples — React, Vue, Angular, Svelte, Solid.
• Adapter examples — MobX, Pinia, Zustand, and the adapter gallery.
• Middleware examples, vanilla reusable store, and Yjs collaboration.

Docs

• Why Coaction Without Multithreading
• Coaction vs Zustand
• Migrating from Zustand
• Architecture Overview
• Threading Model
• Support Matrix
• Core API Reference

FAQs

Contributing

Start with CONTRIBUTING.md. Security reports follow SECURITY.md, and participation is covered by CODE_OF_CONDUCT.md.

Pull request CI is maintainer-gated: a maintainer adds the run-ci label when a PR is ready. Once the label is present, later pushes to the same PR keep running CI.

Credits

• Concept inspired by Partytown
• API design inspired by Zustand
• Technical reference: React + Redux + Comlink = Off-main-thread

License

Coaction is MIT licensed.