zustand-x

To use Zustand X, install it via pnpm. You must also have react and zustand installed in your project.

pnpm add zustand-x

Create a store using createStore and consume its values in React components using useStoreValue or useStoreState. Zustand X automatically provides type-safe access to state fields.

import { createStore, useStoreState, useStoreValue } from 'zustand-x';

// Create a store with an initial state
const repoStore = createStore({
  name: 'ZustandX',
  stars: 0,
});

// Use it in your components
function RepoInfo() {
  const name = useStoreValue(repoStore, 'name');
  const stars = useStoreValue(repoStore, 'stars');

  return (
    <div>
      <h1>{name}</h1>
      <p>{stars} stars</p>
    </div>
  );
}

function AddStarButton() {
  const [, setStars] = useStoreState(repoStore, 'stars');
  return <button onClick={() => setStars((s) => s + 1)}>Add star</button>;
}

If you need to interact with the vanilla Zustand store directly, you can access it via the .store property on the Zustand X store instance.

• Use useStoreSelect(store, selector) to use the original Zustand hook.
• Use store.store to get the vanilla store, which provides .getState(), .setState(), and .subscribe().

// Use the original Zustand hook
const name = useStoreSelect(store, (state) => state.name);

// Get the vanilla store
const vanillaStore = store.store;
vanillaStore.getState();
vanillaStore.setState({ count: 1 });

const unsubscribe = vanillaStore.subscribe((state) =>
  console.log('New state:', state)
);

The store instance provides direct methods for interacting with state outside of React components.

Reading State

• store.get('key'): Get a single value.
• store.get('state'): Get the entire state.
• store.get('selector', ...args): Call a selector with arguments.

Writing State

• store.set('key', value): Set a single value.
• store.set('action', ...args): Call an action.
• store.set('state', (draft) => { ... }): Update multiple values at once. If using immer or mutative, remember to return the draft to maintain compatibility.

// Reading
store.get('name');
store.get('state');
store.get('someSelector', 1, 2);

// Writing
store.set('name', 'Bob');
store.set('someAction', 10);
store.set('state', (draft) => {
  draft.name = 'Bob';
  draft.loggedIn = true;
  return draft;
});

You can augment your store using extendSelectors and extendActions to add computed properties and reusable logic.

Adding Selectors

Use extendSelectors to derive new values. These are automatically memoized.

Adding Actions

Use extendActions to define functions that modify state. You have access to get, set, and existing actions via the callback argument.

const extendedStore = store
  .extendSelectors(({ get }) => ({
    fullName: () => get('firstName') + ' ' + get('lastName'),
  }))
  .extendActions(({ get, set }) => ({
    updateName: (newName: string) => set('name', newName),
    resetState: () => {
      set('state', (draft) => {
        draft.firstName = 'Jane';
        return draft;
      });
    },
  }));

// Usage
extendedStore.get('fullName');
extendedStore.set('updateName', 'Julia');

When calling createStore, you can pass a second argument to configure middleware like devtools, persist, immer, or mutative. Middleware can be enabled via a boolean or a detailed configuration object.

import { createStore } from 'zustand-x';

const userStore = createStore(
  {
    name: 'Alice',
    loggedIn: false,
  },
  {
    name: 'user',
    devtools: true, // Enable Redux DevTools
    persist: true, // Persist to localStorage
    mutative: true, // Enable immer-style mutations
  }
);

You can provide an options object to mutativeMiddleware to configure the underlying mutative behavior. The available options are derived from PatchesOptions (excluding enablePatches).

Note that enablePatches is managed internally by the middleware to ensure compatibility with Zustand's state updates.

// Example of passing options to the middleware
const useStore = create<MyState>()(
  mutativeMiddleware(
    (set) => ({ ... }),
    { /* mutative options here */ }
  )
);

You can pass an optional Options object as the second argument to immerMiddleware to customize Immer's behavior within your store.

import { create } from 'zustand';
import { immerMiddleware, type ImmerOptions } from 'zustand-x';

const useStore = create(
  immerMiddleware(
    (set) => ({
      // ... state definition
    }),
    {
      enableMapSet: true,
      enabledAutoFreeze: true,
    }
  )
);

{
  enableMapSet?: boolean;
  enabledAutoFreeze?: boolean;
}