nexus
Nexus State

Nexus State Quick Start

Build a synchronized remote state store with Nexus.

Before You Start

Configure two communicating Nexus contexts first; see Getting started. One hosts the authoritative store; the other reads a local mirror and invokes remote actions.

What To Install

The headless API is included in @nexus-js/core/state. Add @nexus-js/react only for React bindings; @nexus-js/core/state is an import path, not a package.

1. Define A Store

import { createStoreToken } from "@nexus-js/core/state";

export interface CounterStore {
  count: number;
  increment(by?: number): number;
  reset(): void;
}

export const counterStore = createStoreToken<CounterStore>(
  "example:counter-store",
);

2. Host The Store

Register the Nexus State store like any other Nexus service.

import { nexus } from "@nexus-js/core";
import { createNexusStore } from "@nexus-js/core/state";
import { counterStore } from "./counter-store";

const { provider, store } = createNexusStore(
  counterStore,
  (set, get) => ({
    count: 0,
    increment(by = 1) {
      const count = get().count + by;
      set({ count });
      return count;
    },
    reset() {
      set({ count: 0 });
    },
  }),
  {
    snapshot: (local) => ({ count: local.count }),
    expose: ["increment", "reset"],
  },
);

nexus.configure({
  providers: [provider],
});

console.log(store.getState().count);

provider registers the remote service; store is the original local Zustand store. Use bindNexusStore(...) when the Zustand store already exists.

For native-store lifecycle, ConnectOptions, and safe Result APIs, see the Core API.

3. Connect From Another Context

import { nexus } from "@nexus-js/core";
import { connectNexusStore } from "@nexus-js/core/state";
import { counterStore } from "./counter-store";

const remoteCounter = await connectNexusStore(nexus, counterStore, {
  target: { context: "background" },
});

The returned RemoteStore holds a local mirror. After session replacement, create a new handle with connectNexusStore(...).

4. Read, Subscribe, And Invoke Actions

console.log(remoteCounter.getState().count);

const stop = remoteCounter.subscribe((state) => {
  console.log("count changed", state.count);
});

await remoteCounter.actions.increment(2);

stop();
remoteCounter.destroy();

Headless Lifecycle And Cleanup Recipe

Use this pattern in non-React services, workers, or scripts:

const remote = await connectNexusStore(nexus, counterStore, options);

const unsubscribe = remote.subscribe((state) => {
  // Process remote updates.
  console.log(state);
});

try {
  await remote.actions.increment(1);
  const snapshot = remote.getState();
  console.log(snapshot.count);
} finally {
  // Always unsubscribe the listener and destroy the handle.
  unsubscribe();
  remote.destroy();
}

If a RemoteStore handle becomes terminal, create a new handle instead of reusing it. Do not retry an action automatically after a disconnect because the action may already have completed on the host. See Lifecycle and errors for the full rules.

5. React Usage

For React, wrap your tree with NexusProvider and share a remote handle through a scope:

import { createRemoteStoreScope, NexusProvider } from "@nexus-js/react";

const CounterScope = createRemoteStoreScope(counterStore);

function App({ sessionEpoch }: { sessionEpoch: number }) {
  return (
    <NexusProvider nexus={nexus}>
      <CounterScope.Provider
        options={{
          target: { context: "background" },
          reconnectKey: sessionEpoch,
        }}
      >
        <CounterView />
      </CounterScope.Provider>
    </NexusProvider>
  );
}

function CounterView() {
  const { pending, reconnect } = CounterScope.useRemoteStore();
  const count = CounterScope.useSelector((state) => state.count, {
    fallback: 0,
  });
  const actions = CounterScope.useActions();
  const phase = CounterScope.useStatus((status) => status.type);

  if (pending) return <span>Connecting</span>;
  if (!actions || phase !== "ready") {
    return <button onClick={reconnect}>Reconnect</button>;
  }

  return <button onClick={() => actions.increment(1)}>{count}</button>;
}

The scope provider manages one shared RemoteStore handle for the subtree. Leaf components use useSelector, useActions, and useStatus from that scope instead of each calling useRemoteStore(...) separately. For a direct owner, render a child after remote.store exists and select it with useStore(remote.store, selector) imported from zustand.

See Nexus State React for reconnectKey, reconnect(), replacement, and selector fallback.

Edit this page on GitHub