npm / xstate
xstate
What changed in xstate 5, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-17.
1 breaking11 new APIs and options1 behavior and defaults12 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initxstate 525 changes
Breaking changes 1
Targeting a history state that is a direct child of an unvisited parallel state with no default target now enters the parallel state's initial configuration instead of doing nothing.
New APIs and options 11
Add types.transitionMeta to type transition metadata separately from state metadata; when omitted, types.meta continues to apply to both.
Exports InspectedTransitionEvent from xstate, making it available to developers.
Adds mapState(snapshot, mapper) to map a snapshot to values based on active states.
Adds an option to configure the maximum number of microsteps allowed before throwing an infinite loop error; it defaults to Infinity.
Adds an option to xstate/graph traversal helpers and createTestModel to control which events are explored from each state, enabling enabled-only traversal.
Adds a method that derives a Readable from an actor snapshot, with subscribe and synchronous get access; subscriptions emit only when the selected value changes.
States with route: {} and an explicit id can be navigated to from anywhere using an xstate.route event; routes can also use guards for conditional navigation.
Returns an array of snapshot-and-actions tuples for each microstep in the initial transition.
Returns an array of snapshot-and-actions tuples for each microstep in a transition.
Adds a utility that returns all transitions available from the current state.
Adds a method to incrementally extend machine setup configurations with actions, guards, and delays that can reference base definitions and support chaining.
Behavior and default changes 1
assertEvent now supports partial descriptors, allowing checks for events whose type starts with a given prefix.
Fixes and other changes 12
When an unhandled error from an invoked actor causes a machine to error, remaining invoked and spawned actors are stopped and their cleanup functions called before the machine settles in the error state.
Generic history values, snapshot nodes, and directed graph results now accept arbitrary state and transition metadata consistently, avoiding unsafe-type warnings when inspecting machines through generic APIs.
AnyStateNode, AnyStateNodeDefinition, and AnyTransitionDefinition now widen their metadata parameters to match nodes of an AnyStateMachine, avoiding unsafe-argument and unsafe-return reports.
Machine snapshots retain their machine-specific methods when initialization fails, keeping methods such as snapshot.matches(...) available on error snapshots.
Sending an event containing unserializable data to a stopped actor no longer throws; the development-only warning is emitted safely.
Fixes initialTransition and transition throwing a duplicate system ID error when a machine contains an invoke with a systemId.
When guards on an exact event descriptor all fail, matching wildcard descriptor transitions are now tried as fallback.
Fixes children snapshot union pollution for typed invoke.
Named guards registered with setup({ guards }) are now resolved for route.guard.
Types are exported so setup() declaration emit works.
Fixes cleanup of systemId for nested children when stopChild is used.
Fixes a bug in Cordova when iterating an empty Map.