zustand-actions

Split a zustand store into state and actions while keeping encapsulation.

import { create } from 'zustand';
import { withActions } from 'zustand-actions';

interface Counter {
    //--- State<Counter> ---
    count: number;

    //--- Actions<Counter> ---
    increment: () => void;
    decrement: () => void;
}

const useCounter = create<Counter>()(
    withActions(set => ({
        count: 0,
        increment: () => set(state => ({ count: state.count + 1 })),
        decrement: () => set(state => ({ count: state.count - 1 })),
    })),
);

const { increment } = useCounter.getActions(); // Actions<Counter>
const { count } = useCounter.getState(); // State<Counter>

// setState and selectors are restricted to State<Counter>
useCounter(state => state.count);
useCounter.setState({ count: 1 });

Installation

npm

npm install zustand-actions

bun

bun install zustand-actions

Motivation

A common pattern in zustand is to split the store into state and actions.

A simple way to achieve this is to define actions at module level, see: Practice with no store actions

Or if you prefer to colocate your actions with the state, define them under a separate key and provide a custom hook to access them.

import { type StateCreator, create } from 'zustand';

interface Counter {
    count: number;
    actions: {
        increment: () => void;
        decrement: () => void;
    };
}

const useCounter = create<Counter>()(set => ({
    count: 0,
    actions: {
        increment: () => set(state => ({ count: state.count + 1 })),
        decrement: () => set(state => ({ count: state.count - 1 })),
    },
}));

const useCounterActions = useCounter(state => state.actions);

// this is fine (assuming the 'actions' don't change), no selector needed
const { increment } = useCounterActions;

This has some drawbacks:

• You need to write a separate hook for your actions
• Actions are still part of the state, so they can be changed via setState.

Middlewares to the rescue

zustand-actions provides a middleware withActions to split the store into State and Actions. The setState and getState functions are restricted to the State type. Additionally, the StoreApi provides a getActions function to access the actions, no custom hook needed.

Usage with other middlewares

zustand-actions can be used with other middlewares, such as immer. Just make sure to apply withActions last.

Note: You need to specify the keys of the actions as template arguments to the immer middleware or type the full state creator. You can use the ActionKeys type to extract the keys from the interface.

import { create } from 'zustand';
import { withActions, type ActionKeys } from 'zustand-actions';
import { immer } from 'zustand/middleware/immer';

interface Nested {
    parent: {
        child: {
            count: number;
        };
    };
    increment: () => void;
}

const useNested = create<Nested>()(
    withActions(
        immer<Nested, [['zustand-actions', ActionKeys<Nested>]]>(
            // --- StateCreator<Nested, [['zustand-actions', ActionKeys<Nested>], ['zustand/immer', never]]>
            set => ({
                parent: {
                    child: {
                        count: 0,
                    },
                },
                increment: () => set(draft => void draft.parent.child.count++),
            })
            // ---
        ),
    ),
);

// setState and draft are restricted to State<Nested>
useNested.setState(draft => {
    draft.parent.child.count = 1;
});

Unknown Types

The middleware supports store interfaces that are not fully typed, e.g. containing any or template parameters.

However, the State and Actions can not be inferred automatically in this case. We recommend splitting your interface into state and actions manually instead. You still keep all the benefits of the withActions middleware.

Note: You need to specify the keys of the actions as the second argument to the store mutators.

Example using generic types

interface GenericState<T> {
    name: string;
    value: T;
}

interface GenericActions<T> {
    setValue: (value: T) => void;
}

type Generic<T> = GenericState<T> & GenericActions<T>;

type GenericStore<T> = Mutate<
    StoreApi<Generic<T>>,
    [['zustand-actions', keyof GenericActions<T>] /*, <other middlewares> */]
>;

function createGeneric<T>(
    name: string,
    initialValue: T,
): StateCreator<Generic<T>, [['zustand-actions', keyof GenericActions<T>] /*, <other middlewares */]> {
    return set => ({
        name,
        value: initialValue,
        setValue: value => set({ value }),
    });
}

function createGenericStore<T>(name: string, initialValue: T): GenericStore<T> {
    return createStore<Generic<T>>()(withActions(createGeneric(name, initialValue)));
}

function useGeneric<T>(name: string, initialValue: T): UseBoundStore<GenericStore<T>> {
    return create<Generic<T>>()(withActions(createGeneric(name, initialValue)));
}