Registry / web-framework / zustand-middleware-xstate

zustand-middleware-xstate

JSON →
library3.0.1jsnpmunverified

Zustand middleware for integrating XState state machines into a global Zustand store. Currently at version 3.0.1, this package is designed to work seamlessly with XState v5 and Zustand v4, ensuring compatibility with their latest APIs and features. It provides a straightforward mechanism to create a Zustand store from an XState machine, exposing the machine's current `state`, the `send` event function, and the underlying `actor` for component consumption. This enables developers to leverage Zustand's reactive state management and selector capabilities to optimize re-renders while benefiting from XState's robust state orchestration. The middleware also allows passing actor options, such as `devTools`, directly to the XState actor, enhancing debugging and development workflows. While specific release cadences aren't explicitly stated, its alignment with major versions of its peer dependencies suggests active maintenance in response to their evolution.

npm install zustand-middleware-xstate
INSTALL
IMPORT
SIG · ZUSTAND-MIDDLEWARE
Z
zustand-middleware-xstate
web-frameworkjavascriptv3.0.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

create
import create from 'zustand'
import { create } from 'zustand'
Zustand v4+ exports `create` as a default export. Using named import will result in `undefined`.
setup
import { setup } from 'xstate'
import setup from 'xstate'
XState v5 exports `setup` as a named export. It's crucial for defining machine types and configurations in v5.
xstate
import xstate from 'zustand-middleware-xstate'
import { xstate } from 'zustand-middleware-xstate'
The middleware function `xstate` is the default export from this package.

Demonstrates creating an XState machine, integrating it into a Zustand store with the middleware, and accessing state and send function.

import create from "zustand"; import { setup } from "xstate"; import xstate from "zustand-middleware-xstate"; type UserEvents = { type: 'LOGIN' } | { type: 'LOGOUT' }; // Create your XState machine definition using setup const authMachine = setup({ types: { events: {} as UserEvents, context: {} as { userId: string | null } }, }).createMachine({ id: "auth", initial: "loggedOut", context: { userId: null }, states: { loggedOut: { on: { LOGIN: { target: "loggedIn", actions: ({ context }) => { // In a real app, you'd set the actual user ID context.userId = 'some-user-id-' + Math.random().toFixed(2); } } } }, loggedIn: { on: { LOGOUT: { target: "loggedOut", actions: ({ context }) => { context.userId = null; } } } } } }); // Create a Zustand store hook using the xstate middleware const useAuthStore = create( xstate(authMachine, { devTools: process.env.NODE_ENV === 'development' }) ); // Example usage in a component-like structure const AuthComponent = () => { const { state, send, actor } = useAuthStore(); console.log('Current Auth State:', state.value); console.log('User ID:', state.context.userId); return ( <div> <p>Authentication Status: {String(state.value)}</p> {state.matches('loggedOut') && ( <button onClick={() => send({ type: 'LOGIN' })}>Login</button> )} {state.matches('loggedIn') && ( <button onClick={() => send({ type: 'LOGOUT' })}>Logout</button> )} <p>Actor status: {actor.getSnapshot().status}</p> </div> ); }; // Simulate rendering AuthComponent(); // Initial render useAuthStore.getState().send({ type: 'LOGIN' }); // Simulate user login AuthComponent(); // Re-render after login useAuthStore.getState().send({ type: 'LOGOUT' }); // Simulate user logout AuthComponent(); // Re-render after logout
Debug
Known issues
breakingThis middleware requires XState v5+ and Zustand v4+ as peer dependencies. Older versions of XState (e.g., v4) are not compatible due to significant API changes in XState v5, particularly around machine creation and actor management.
fix
Ensure your project uses `xstate@^5.15.0` and `zustand@^4.1.4` (or compatible versions) by upgrading your `package.json` dependencies and running `npm install`.
affects: <3.0.0
gotchaWhen migrating from XState v4, remember that XState v5 introduces the `setup` API for machine definition. Directly passing old XState v4 machine definition objects will lead to runtime errors.
fix
Refactor your XState machine definitions to use `setup({ ... }).createMachine({ ... })` as shown in the XState v5 documentation and the quickstart example.
affects: >=3.0.0
gotchaThe `create` function from `zustand` is a default export in v4+, not a named export. Incorrect import syntax will cause runtime errors.
fix
Use `import create from 'zustand'` instead of `import { create } from 'zustand'` for Zustand v4 and newer.
affects: >=3.0.0
gotchaThe `xstate` middleware expects an already created XState machine instance (the return value of `setup(...).createMachine(...)`), not just a plain machine configuration object.
fix
Always pass the result of `setup({ ... }).createMachine({ ... })` to the `xstate` middleware function.
affects: >=3.0.0
Errors
Common errors & fixes
TypeError: create is not a function
Attempting to import `create` from 'zustand' as a named export when it is a default export in Zustand v4+.
fix
Change `import { create } from 'zustand'` to `import create from 'zustand'`.
TypeError: machine.createMachine is not a function
Passing an XState v4 machine definition or an incorrectly structured object to the middleware, which expects an XState v5 machine created with `setup().createMachine()`.
fix
Ensure your XState machine is created using `const machine = setup({ ... }).createMachine({ ... });` before passing `machine` to `xstate(machine)`.
TypeError: Cannot read properties of undefined (reading 'value') when accessing state.value
This usually indicates the XState machine or the Zustand store was not correctly initialized, or a peer dependency (XState/Zustand) version mismatch is preventing the middleware from creating a valid machine instance.
fix
Verify that `xstate` (v5+) and `zustand` (v4+) are correctly installed and that the machine passed to the middleware is a valid XState v5 machine instance. Check console for earlier initialization errors.
Upgrade
Version history
3.0.1latest on npm
Audit
Dependencies
xstaterequiredPeer dependency required for state machine logic (v5+).
zustandrequiredPeer dependency required for state management (v4+).
Agent activity
56 hits · last 30 days
node
48
Perplexity
1
OpenAI (training)
1
Resources
zustand-middleware-xstate — npm install zustand-middleware-xstate · libregistry