{"id":49800,"library":"xstate-migrate","title":"xstate-migrate","description":"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.","status":"active","version":"0.0.8","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","xstate","state machine","migration","typescript"],"install":[{"cmd":"npm install xstate-migrate","lang":"bash","label":"npm"},{"cmd":"yarn add xstate-migrate","lang":"bash","label":"yarn"},{"cmd":"pnpm add xstate-migrate","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; required to define machines, create actors, and get snapshots. Only v5.28+ supported.","package":"xstate","optional":false}],"imports":[{"note":"ESM-only package; named import required.","wrong":"const xstateMigrate = require('xstate-migrate')","symbol":"xstateMigrate","correct":"import { xstateMigrate } from 'xstate-migrate'"},{"note":"Named export available as a standalone function; also accessible as a method on the default object.","wrong":"import { xstateMigrate } from 'xstate-migrate';\nxstateMigrate.generateMigrations(...)","symbol":"generateMigrations","correct":"import { generateMigrations } from 'xstate-migrate'"},{"note":"Named export for applying migrations directly.","wrong":"","symbol":"applyMigrations","correct":"import { applyMigrations } from 'xstate-migrate'"}],"quickstart":{"code":"import { createMachine, createActor } from 'xstate';\nimport { xstateMigrate } from 'xstate-migrate';\n\n// Define machines\nconst machineV1 = createMachine({\n  types: { input: {} as { initialData: string }, context: {} as { data: string } },\n  id: 'example',\n  initial: 'idle',\n  context: ({ input }) => ({ data: input.initialData }),\n  states: { idle: { on: { NEXT: 'active' } }, active: {} },\n});\n\nconst actor = createActor(machineV1, { input: { initialData: 'Hello' } }).start();\nactor.send({ type: 'NEXT' });\nconst persistedSnapshot = actor.getSnapshot();\n\nconst machineV2 = createMachine({\n  types: { input: {} as { initialData: string }, context: {} as { data: string; newData: number } },\n  id: 'example',\n  initial: 'idle',\n  context: ({ input }) => ({ data: input.initialData, newData: 0 }),\n  states: { idle: { on: { NEXT: 'active' } }, active: {}, newState: {} },\n});\n\n// Generate and apply migrations\nconst migrations = xstateMigrate.generateMigrations(machineV2, persistedSnapshot, { initialData: 'Hello' });\nconst migratedSnapshot = xstateMigrate.applyMigrations(persistedSnapshot, migrations);\nconsole.log(migratedSnapshot); // { context: { data: 'Hello', newData: 0 }, value: 'active' }","lang":"typescript","description":"Generates and applies migration patches between two XState machine versions, preserving existing context."},"warnings":[{"fix":"Upgrade to xstate@^5.28.0.","message":"Requires XState v5.28 or higher; incompatible with older versions (v4.x).","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Always provide the input argument when calling generateMigrations, even if the input type is undefined.","message":"The generateMigrations function requires the input for the new machine; if omitted, generated patches may be incorrect for machines that depend on input.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Ensure the persisted snapshot's state value is reachable in the new machine; manually review generated patches.","message":"Migration 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.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Pin to exact version and test migrations after updates.","message":"Package is at version 0.0.8 and may have API changes before 1.0.0.","severity":"deprecated","affected_versions":"<1.0.0"}],"env_vars":null,"search_vec":"'0':82 'additions/removals':56 'autom':66 'chang':33 'comparison':70 'configur':25 'context':40,54,76 'current':78 'definit':48 'depend':63 'describ':32 'develop':81 'differ':20 'differenti':65 'earli':80 'enabl':16 'exist':75 'generat':27,68 'includ':87 'initi':72 'javascript':88 'json':28 'key':64 'librari':11 'machin':15,24,47,52,91 'match':44 'migrat':3,6,10,67,92 'need':34 'nested/parallel':50 'new':46 'oper':30 'patch':29 'peer':62 'persist':13,38 'preserv':74 'properti':55 'requir':57 'seamless':17 'snapshot':39,73 'state':23,42,51,90 'support':49 'transit':18 'type':86 'typescript':85,93 'updat':36 'v0.0.8':7 'v5.28':59 'valu':77 'version':21 'via':69 'x':83 'xstate':2,5,14,58,89 'xstate-migr':1,4","created_at":"2026-06-07T17:03:40.301168+00:00","updated_at":"2026-06-07T17:03:40.301168+00:00","problems":[{"fix":"Ensure persistedSnapshot is a valid XState machine snapshot object before calling applyMigrations.","cause":"PersistedSnapshot passed to applyMigrations is undefined or null.","error":"TypeError: Cannot read properties of undefined (reading 'context')"},{"fix":"Only use patches generated by generateMigrations; do not manually construct custom operations.","cause":"Attempting to use a JSON Patch directive not generated by xstate-migrate.","error":"Error: Unsupported operation: replace"},{"fix":"Provide input that matches the new machine's types.input definition.","cause":"Input argument passed to generateMigrations does not match the new machine's input type.","error":"Error: Input type mismatch: expected <type>, got <type>"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"xstate-migrate","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}