xstate-migrate

library0.0.8jsnpmunverified

xstate-migrate (v0.0.8) is a migration library for persisted XState machines, enabling seamless transitions between different versions of state machine configurations. It generates JSON Patch operations that describe changes needed to update a persisted snapshot (context and state) to match a new machine definition. Supports nested/parallel state machines and context property additions/removals. Requires XState v5.28+ as a peer dependency. Key differentiator: automates migration generation via comparison of initial snapshots, preserving existing context values. Currently in early development (0.x), with TypeScript types included.

devops

npm install xstate-migrate

package ↗

INSTALL

IMPORT

SIG · XSTATE-MIGRATE

xstate-migrate

devopsjavascriptv0.0.8

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

xstateMigrate

✓ import { xstateMigrate } from 'xstate-migrate'

✗ const xstateMigrate = require('xstate-migrate')

ESM-only package; named import required.

generateMigrations

✓ import { generateMigrations } from 'xstate-migrate'

✗ import { xstateMigrate } from 'xstate-migrate'; xstateMigrate.generateMigrations(...)

Named export available as a standalone function; also accessible as a method on the default object.

applyMigrations

✓ import { applyMigrations } from 'xstate-migrate'

Named export for applying migrations directly.

Generates and applies migration patches between two XState machine versions, preserving existing context.

import { createMachine, createActor } from 'xstate'; import { xstateMigrate } from 'xstate-migrate'; // Define machines const machineV1 = createMachine({ types: { input: {} as { initialData: string }, context: {} as { data: string } }, id: 'example', initial: 'idle', context: ({ input }) => ({ data: input.initialData }), states: { idle: { on: { NEXT: 'active' } }, active: {} }, }); const actor = createActor(machineV1, { input: { initialData: 'Hello' } }).start(); actor.send({ type: 'NEXT' }); const persistedSnapshot = actor.getSnapshot(); const machineV2 = createMachine({ types: { input: {} as { initialData: string }, context: {} as { data: string; newData: number } }, id: 'example', initial: 'idle', context: ({ input }) => ({ data: input.initialData, newData: 0 }), states: { idle: { on: { NEXT: 'active' } }, active: {}, newState: {} }, }); // Generate and apply migrations const migrations = xstateMigrate.generateMigrations(machineV2, persistedSnapshot, { initialData: 'Hello' }); const migratedSnapshot = xstateMigrate.applyMigrations(persistedSnapshot, migrations); console.log(migratedSnapshot); // { context: { data: 'Hello', newData: 0 }, value: 'active' }

Debug

Known issues

breakingRequires XState v5.28 or higher; incompatible with older versions (v4.x).

fix

Upgrade to xstate@^5.28.0.

affects: >=0.0.0

gotchaThe generateMigrations function requires the input for the new machine; if omitted, generated patches may be incorrect for machines that depend on input.

fix

Always provide the input argument when calling generateMigrations, even if the input type is undefined.

affects: >=0.0.0

gotchaMigration patches are generated based on the initial snapshot of the new machine; if the persisted snapshot has a different state path, transitions might not match exactly, leading to incomplete patches.

fix

Ensure the persisted snapshot's state value is reachable in the new machine; manually review generated patches.

affects: >=0.0.0

deprecatedPackage is at version 0.0.8 and may have API changes before 1.0.0.

fix

Pin to exact version and test migrations after updates.

affects: <1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'context')

PersistedSnapshot passed to applyMigrations is undefined or null.

fix

Ensure persistedSnapshot is a valid XState machine snapshot object before calling applyMigrations.

Error: Unsupported operation: replace

Attempting to use a JSON Patch directive not generated by xstate-migrate.

fix

Only use patches generated by generateMigrations; do not manually construct custom operations.

Error: Input type mismatch: expected <type>, got <type>

Input argument passed to generateMigrations does not match the new machine's input type.

fix

Provide input that matches the new machine's types.input definition.

Upgrade

Version history

0.0.8latest on npm

Audit

Dependencies

xstaterequiredPeer dependency; required to define machines, create actors, and get snapshots. Only v5.28+ supported.

Agent activity

11 hits · last 30 days

node

Amazon

Resources

packagexstate-migrate ↗