XState release notes, breaking changes, and upgrade notes.
Actor-based state management and orchestration StackPulse turns upstream changelogs into scannable summaries with risky changes, deprecations, migration notes, and source links.
This release updates the codemod package alongside xstate@6.0.0-beta.3. Its notes describe a breaking `xstate/fsm` transition API change, add eventless `always` transitions, and provide a codemod transform to update inline FSM configurations.
affected
Users of `xstate/fsm` configurations or transition functions that use string targets or return strings are affected.
action
Apply the `string-targets` codemod to inline FSM configurations and manually review separately stored configurations and transition functions.
release_signals
-In `xstate/fsm`, `on` and `always` transition targets must now be objects, such as `{ target: 'ready' }`, rather than strings. Transition functions must return an object or `undefined`; `initial: 'idle'` remains unchanged.
+`xstate/fsm` supports eventless `always` transitions during initialization and after handled events until no eventless transition is enabled.
migration_steps2 steps
01Run the `@xstate/codemod` `string-targets` transform to update inline FSM configurations.
02Review separately stored configurations and functions returning strings manually.
This beta adds eventless `always` transitions to `xstate/fsm` and changes how callback, observable, listener, and subscription actors process and report events sent to a parent. It also fixes event ordering for delayed events and prevents targetless reentering transitions from running entry behavior.
affected
Users of `xstate/fsm` with string transition targets or string-returning transition functions must update those configurations; users of the affected actor types receive changed event processing and inspection/subscriber notifications.
action
Update FSM transition targets to object form and review separately stored configurations and transition functions before upgrading.
release_signals
-`xstate/fsm` now requires object transition targets for `on` and `always`; for example, replace `on: { GO: 'ready' }` with `on: { GO: { target: 'ready' } }`.
Serialized snapshot and effect-descriptor fields that began with `$` or `_` have been renamed to storage-compatible names, addressing restrictions in databases such as Convex and MongoDB. Restore functions continue to accept snapshots with the old field names, but newly serialized snapshots use the new names and omit private counter fields from `snapshot.toJSON()`.
affected
Users persisting or consuming serialized snapshots, systemTransition snapshots, effect descriptors, or @xstate/test traces are affected; restore functions continue to read both old and new snapshot shapes.
action
Update persisted-snapshot validation schemas and any consumers that depend on the renamed serialized fields.
release_signals
-Serialized field names changed: `$actor`, `$error`, `$stateNode`, and `$systemMapper` now use `@` prefixes; `_nextTimerId`, `_nextActorIds`, and `_stateInputs` no longer use underscore prefixes. Consumers expecting the old serialized shape, including schema validators, must account for the new names.
Serialized snapshots and effect-related descriptors now use field names without `$` or `_` prefixes, improving compatibility with persistence stores that reject those names. The release also exports `sendAndAwait` from the main entrypoint and updates effect actor observer ordering and stop behavior to align with `createActor`.
affected
Users persisting or validating XState snapshots and consumers of serialized effect descriptors are affected by the renamed fields; restore functions continue to accept snapshots with the old names.
action
Update snapshot-validation schemas to the new field names before relying on newly serialized snapshots.
This release updates the codemod package’s XState dependency to 6.0.0-beta.2, which changes serialized snapshot and descriptor field names to avoid `$` and `_` prefixes that some databases reject. Restore APIs continue to accept snapshots written with the old names, but new snapshots use the new names and schemas that validate persisted snapshots must be updated accordingly.
affected
Users persisting or validating XState snapshots, system transition snapshots, or effect descriptors are affected by the serialized field-name changes.
action
Update persisted-snapshot validation schemas to use the new field names; no snapshot rewrite is required for restoration because the documented restore APIs accept both shapes.
release_signals
-Serialized output now uses `@actor`, `@error`, `@stateNode`, and `@systemMapper` instead of the corresponding `$`-prefixed names, and uses `nextTimerId`, `nextActorIds`, and `stateInputs` instead of underscore-prefixed names where applicable. New persisted snapshot schemas, including those using `machineVersions`, must use the new names.
This beta changes serialized snapshot and related output field names to avoid `$` and `_` prefixes, while retaining compatibility when restoring snapshots written by beta.1. It also adds durable checkpoints that preserve transition progress and queued root events, alongside fixes for FSM behavior, typing, snapshot retention, and inspector event reporting.
affected
Users persisting or validating snapshots and consumers of serialized actor references or effect descriptors are affected by the renamed fields; durable execution users can use the new checkpoint format to preserve queued events across restoration.
action
Update persisted-snapshot validation schemas to the new field names and use `durable.checkpoint(snapshot)` when checkpointing durable executions that need to preserve queued root events.
The Vue hooks `useActorRef`, `useActor`, and `useMachine` can now accept an already-created actor, including one restored with `restoreActor`. The `snapshot` option is removed; XState v6 has entered beta, with no further breaking changes planned for `@public` APIs and possible changes to `@experimental` APIs.
affected
Vue users who restore or otherwise create actors before passing them to these hooks are affected; users of `@experimental` APIs should note those APIs may still change.
action
If using the removed `snapshot` option, migrate to `restoreActor` and pass the restored actor to the hook.
release_signals
-The hooks’ `snapshot` option is removed. Restore an actor with `restoreActor` from `xstate/persist` and pass the actor to a hook instead.
The Svelte hooks `useActorRef`, `useActor`, and `useMachine` now accept an already-created actor, including one restored with `restoreActor`. The `snapshot` option is removed; the hook starts the supplied actor and stops it when the component is destroyed. This release also marks XState v6 as beta, with no further breaking changes planned for `@public` APIs and possible changes to `@experimental` APIs.
affected
Svelte users who restore actor state or use the removed `snapshot` option are affected.
action
Update code using the `snapshot` option to restore and pass an actor as shown in the release notes.
release_signals
-The `snapshot` option is removed; restore an actor with `restoreActor` from `xstate/persist` and pass the actor to the hook instead.
The Solid hooks `useActorRef`, `useActor`, and `useMachine` now accept an already-created actor, including one restored with `restoreActor`. The `snapshot` option is removed; hooks start the supplied actor on mount and stop it on unmount. XState v6 is in beta, with no further breaking changes planned for `@public` APIs, while `@experimental` APIs may still change.
affected
Solid users of `useActorRef`, `useActor`, or `useMachine` who rely on the removed `snapshot` option are affected, as are users adopting restored actors.
action
Update code that uses the `snapshot` option to pass an actor restored with `restoreActor` instead.
release_signals
-The `snapshot` option is removed from the hooks; restore an actor with `restoreActor` from `xstate/persist` and pass the actor to a hook instead.
XState v6 beta moves persisted actor restoration from `createActor` to `restoreActor` in the `xstate/persist` entry point, and adds snapshot and event validation during restoration. It also makes leftover v5 configuration and unsupported actor options throw, changes macrosteps to be unbounded by default, and improves diagnostics and TypeScript actor-ref types.
affected
Users upgrading to XState v6, especially those restoring persisted actors or carrying v5 configuration and lifecycle event patterns, must update affected APIs and configuration.
action
Review the migration changes before upgrading; use `restoreActor` for persisted snapshots and update v5 configuration or lifecycle event patterns that now throw.
release_signals
-`createActor` no longer restores persisted snapshots; passing `snapshot` throws. Use `restoreActor` instead.
-FSM transition functions must return an object or `undefined`, rather than a string.
+Added eventless `always` transitions to `xstate/fsm`, evaluated during initialization and after handled events until none are enabled.
+Callback, event observable, listener, subscription, and `createEffectEventStreamLogic` actors now process events sent to a parent in their own transitions; inspection and subscribers report the source transition.
migration_steps2 steps
01Run the `@xstate/codemod` `string-targets` transform for inline FSM configurations.
02Manually review separately stored FSM configurations and transition functions that return strings.
Serialized field names changed: for example, `$actor` is now `@actor`, `$error` is now `@error`, and private counters such as `_nextTimerId` and `_nextActorIds` are now `nextTimerId` and `nextActorIds`. Consumers that validate or process serialized snapshots and descriptors must account for the new names. Restore functions remain compatible with snapshots using the old names.
-`snapshot.toJSON()` no longer includes the private `_nextTimerId` and `_nextActorIds` counters.
+Export `sendAndAwait` from the main `@xstate/effect` entrypoint; the test entrypoint continues to re-export it for compatibility.
+Preserve registered Effect action keys in transition descriptors so consumers can identify enqueued actions.
migration_steps1 steps
01Update schemas that validate persisted snapshots (for example, schemas using `machineVersions`) to use the new serialized field names.
-`snapshot.toJSON()` no longer includes the private `_nextTimerId` and `_nextActorIds` counters.
migration_steps1 steps
01Update schemas that validate persisted snapshots (for example, schemas using `machineVersions`) to recognize the new field names. Existing snapshots with the old names remain readable by `restoreActor`, `restoreMachineSnapshot`, and `systemTransition`.
Serialized output renames fields such as `$actor`, `$error`, `$stateNode`, `$systemMapper`, `_nextTimerId`, and `_nextActorIds` to names without `$` or `_` prefixes. Consumers and validators of newly written snapshots must use the new names; older beta.1 snapshots remain restorable.
-`snapshot.toJSON()` no longer includes the private `_nextTimerId` and `_nextActorIds` counters.
+Add `durable.checkpoint(snapshot)`, which captures the persisted snapshot, next transition index, and queued root-addressed events for `restore()`.
+Allow `restore()` to accept the new durable checkpoint format while continuing to accept a bare persisted snapshot.
migration_steps1 steps
01Update schemas that validate persisted snapshots, including schemas using `machineVersions`, to use the new serialized field names.
`useActorRef`, `useActor`, and `useMachine` accept an existing actor; hooks start it on mount and stop it on unmount.
migration_steps1 steps
01Replace use of the removed `snapshot` option by restoring the actor with `restoreActor` from `xstate/persist` and passing it to the hook. Create the actor once per component instance.
-`machine.restoreSnapshot()` is removed, and `machine.snapshotSchema` and `machine.eventSchema` are replaced by functions.
-Leftover v5 machine configuration, implementations passed as a second argument to `createMachine`, and unsupported `createActor` options now throw in every build.
-v5 suffixed lifecycle event types in `on` transitions now throw; use the category event type and select the child with `matches`.
-Macrosteps are unbounded by default; configure `options.maxIterations` to make a runaway macrostep throw `InfiniteTransitionError`.
+Adds `restoreActor(logic, snapshot, options?)` via `xstate/persist` for restoring persisted actors, including invoked and spawned children.
+Adds `snapshotSchema(machine)` and `eventSchema(machine)` functions for validating machine snapshots and events.
+Production errors and diagnostics now use short codes with links to the error reference.
migration_steps5 steps
01Replace `createActor(machine, { snapshot: persisted })` with `restoreActor(machine, persisted)` imported from `xstate/persist`; pass the system through the third argument when restoring into a system.
02Replace `machine.snapshotSchema` and `machine.eventSchema` validation with `snapshotSchema(machine)` from `xstate/persist` and `eventSchema(machine)` from `xstate`.
03Declare implementations in `setup({ ... })` or pass them through `machine.provide({ ... })` instead of passing them to `createMachine`.
04Replace removed actor options with their stated replacements; for `systemId`, use `registryKey` and look up the actor with `system.get(registryKey)`.
05Replace v5 suffixed lifecycle event transitions with the category event type and use `matches` to select the child.