TL;DR

XState Store v4 introduces a major overhaul with significant API changes, focusing on modernizing package entrypoints and adding reusable store definitions via createStoreLogic.

Breaking

• createStoreWithProducer is removed; use produce within createStore event handlers.
• Framework-specific packages (e.g., @xstate/store-react) are now required instead of sub-paths (e.g., @xstate/store/react).
• Deprecated undoRedo config wrapping is removed; use the extension form (.with(undoRedo())).
• Computed atoms now receive only the previous value; use .get() to read other atoms.

New

• createStoreLogic enables defining reusable store definitions, usable in framework hooks.
• enq.trigger allows enqueueing store events directly from state machine transitions.
• Store schemas are now exposed via store.schemas for runtime access (schemas define data structures).

Fixes Worth Knowing

• persist helpers now support asynchronous storage results, handling promises from storage operations.

Before You Upgrade

• Update your imports to use the new framework-specific packages (e.g., @xstate/store-react).
• Migrate any uses of the deprecated undoRedo config to the extension form.
• Adjust computed atom logic to use .get() for accessing other atom values.

TL;DR

The @xstate/store packages have been modernized for v4, introducing framework-specific packages (like @xstate/store-react) and a new createStoreLogic function for reusable store definitions.

Breaking

• Package Structure: The way you import store integrations has changed. Use framework-specific packages (e.g., @xstate/store-react) instead of @xstate/store/react.
• ESM Entrypoints: Store packages now publish ECMAScript Modules (ESM).

New

• Reusable Store Logic: createStoreLogic allows you to define store logic separately and reuse it across components.
• Atom Configs: createAtomConfig provides a way to define reusable atom definitions for use with various frameworks.

Before You Upgrade

• Update your import statements to use the new framework-specific packages (e.g., change import { useStore } from '@xstate/store/react' to import { useStore } from '@xstate/store-react').

TL;DR

XState now exports InspectedTransitionEvent, allowing easier access to detailed information about state machine transitions (data passed during transitions).

New

• InspectedTransitionEvent is now exported, providing more detailed transition event data for debugging and advanced use cases.

TL;DR

XState Store now correctly handles dependency tracking within atom.subscribe() callbacks, ensuring callbacks only re-run when relevant atom values change, improving performance and preventing unexpected updates.

Fixes Worth Knowing

• atom.subscribe() callbacks now correctly re-run after synchronous updates to dependencies.
• Fixed an issue where atom.subscribe() callbacks were unnecessarily re-running due to tracking dependencies from .get() calls.
• Resolved a problem with broken exports caused by a publishing workflow issue.

TL;DR

XState React now throws errors when an actor reaches an error state, enabling use with React Error Boundaries (component for graceful error handling).

Breaking

• useActor and useSelector throw on actor errors (requires React Error Boundaries to prevent unhandled rejections).

TL;DR

New integrations with XState allow you to connect state machines directly to your UI in Angular, React, Vue, Svelte, Solid, and Preact, simplifying state management in frontend applications.

Breaking

None.

New

• Framework Integrations: New packages provide direct integration with popular frontend frameworks (Angular, React, Vue, Svelte, Solid, Preact).
• Store Updates: All integrations are built on @xstate/store version 3.15.0.

Fixes Worth Knowing

The compare argument now requires a direct comparison function across all framework integrations.

Before You Upgrade

Ensure your project dependencies are compatible with @xstate/[email protected] if you are using these new integrations.

TL;DR

XState for SolidJS now prevents unintended context mutations when updating array indexes, improving application state predictability.

Fixes Worth Knowing

Updating array indexes in your XState machines (statecharts) with object or array values will no longer modify the original machine context, preventing unexpected behavior.

Before You Upgrade

Review any logic relying on mutating context values via array index updates to ensure it aligns with the new, non-mutating behavior.

TL;DR

XState Graph now supports XState v5, enabling users to visualize and debug more complex state machines.

Breaking

• Graph visualizations may require adjustments due to underlying changes in XState v5 (state machine definition).

New

• Improved compatibility with the latest XState version (state management library).

Fixes Worth Knowing

• None.

Before You Upgrade

• Ensure your XState packages are updated to v5 before upgrading @xstate/graph.

TL;DR

The XState test utilities are now compatible with XState v5, enabling testing of state machines built with the latest version.

New

• Updated to support XState v5 (state machine library).

Before You Upgrade

• Update your XState dependency to v5 to take full advantage of this compatibility.

TL;DR

XState React integration has been significantly overhauled, introducing useActor and useSelector hooks for more direct access to actor state and streamlined event sending, and deprecating older approaches like useService. This release focuses on improved type safety, performance, and alignment with core XState concepts.

Breaking

• useService is deprecated; use useActor instead.
• Factory functions for useMachine and useInterpret are no longer supported.
• FSM-related functions have been removed.
• useSpawn is removed in favor of useActorRef.
• asEffect and asLayoutEffect action creators were removed.

New

• useActor hook provides access to actor state and send function.
• useSelector hook allows selecting derived state from an actor.
• useActorRef returns an ActorRef from actor logic.
• createActorContext helper simplifies global actor management with React Context.

Fixes Worth Knowing

• Fast refresh now works as expected.
• Compatibility with older React versions (React 17).
• Fixed issues with stale state and incorrect typing in hooks.

TL;DR

XState is undergoing significant changes in preparation for v5, focusing on action creators and error handling. The biggest shift is replacing pure and choose actions with the more versatile enqueueActions.

Breaking

• The escalate() action has been removed; use standard error throwing instead.
• state option in createActor is now snapshot.
• getPersistedState() is now getPersistedSnapshot().
• ActorRef type parameters are reordered to <TSnapshot, TEvent>.
• pure() and choose() action creators are removed; use enqueueActions().
• spawn() is now spawnChild(), and stop() is now stopChild().
• MachineSnapshot['nextEvents'] has been removed.

New

• enqueueActions() provides a flexible way to manage actions, replacing pure and choose.
• Strong typing for state values and snapshot.matches() when using the setup API.

Fixes Worth Knowing

• Error handling is now more consistent, with errors available at `snapshot.

TL;DR

The XState Vue integration now returns snapshot and actorRef from useMachine instead of state and service, aligning with the core XState actor model.

Breaking

• useMachine hook return value changed (updates to component data access).
• useInterpret and useSpawn hooks removed (use useActorRef instead - a core XState concept).

Before You Upgrade

Update your components to access the machine's current state via snapshot instead of state. Migrate any usages of useInterpret or useSpawn to useActorRef.