TL;DR

XState now handles events with unserializable data (like circular references) sent to stopped actors without throwing errors, improving robustness in applications using state machines.

Fixes Worth Knowing

Sending events to stopped actors will no longer cause errors when the event data contains complex, non-serializable objects. This prevents unexpected crashes and ensures warnings about sending events to stopped actors are always displayed.

TL;DR

XState gains a new createFSM function for building simple, actor-compatible finite state machines, alongside significant improvements to typing and error handling within state machines, particularly around context, schemas, and invoked actors.

Breaking

• Function-syntax transitions: Now correctly pass input to target state entry actions, potentially changing behavior if you relied on the previous silent ignoring of input.
• Final state output: Machines with defined schemas.output now type-check final state output values, potentially causing type errors if the output doesn't conform to the schema.

New

• createFSM: A new function for creating flat finite state machines with XState-style transitions and actor compatibility. (Simplified state machines)
• createSystem: Enables typed actor registries for managing and accessing actors within a system. (Actor management)
• State-level onError: Allows handling of actor, execution, and communication errors directly within states, providing more granular error management.

Fixes Worth Knowing

• snapshot.matches(...) now correctly narrows types for repeated checks.
• Object transition configs support dynamic context patching with a context mapper.
• Empty schema event objects now infer as type-only events.
• Invoked actor onDone callbacks now receive the actor's output type.

Before You Upgrade

• Review any function-syntax transitions to ensure the input is correctly handled in target state entry actions.
• If you define schemas.output, verify that your final state output values conform to the defined schema.

TL;DR

XState now correctly emits events and executes effects defined within state machine transitions when using fromStore (a state management tool), resolving a silent drop issue.

Fixes Worth Knowing

Events and effects queued within transitions using fromStore will now reliably trigger, ensuring expected behavior for state updates and side effects.

TL;DR

XState Store now correctly infers types for context parameters when using input functions with createStoreLogic, improving type safety for state management (application logic).

Fixes Worth Knowing

Type inference for context parameters in createStoreLogic is now accurate when using input functions, resolving issues with TypeScript definitions.

TL;DR

The useSelector hook in XState stores for React, Preact, Vue, Solid, and Svelte now correctly types the previous value as non-optional, improving type safety when using a custom compare function (custom comparison).

Fixes Worth Knowing

The typing for the compare function used with useSelector has been refined across multiple framework integrations. This resolves a potential type mismatch where the previous state value was incorrectly inferred as potentially undefined, leading to stricter type checking and fewer errors.

TL;DR

XState for SolidJS now requires XState v6, bringing performance improvements and a new architecture for state management (finite state machines).

Breaking

• XState v6 dependency (core state management library) – update your XState package.

Before You Upgrade

• Update your project's XState dependency to version 6.0.0-alpha.0 or later.

TL;DR

@xstate/react now fully supports XState v6, simplifying state machine rehydration in development mode by recreating actors instead of attempting to rehydrate them.

Breaking

• Strict Mode Rehydration Removed: The internal mechanism for rehydrating actors in Strict Mode (a development aid) is removed. Actors will now be recreated on remount, behaving consistently with XState v6. (This only affects development; production behavior is unchanged.)

Before You Upgrade

• If you rely on specific behavior related to Strict Mode rehydration, be aware that actors will now be fully restarted on remount during development.

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 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

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 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.