xstate

Use this skill when working with XState v5 - a state management and orchestration library using state machines, statecharts, and the actor model for complex logic in JavaScript/TypeScript applications.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill provides comprehensive assistance for XState v5, a state management and orchestration library. It helps developers design robust application logic using state machines, statecharts, and the actor model in JavaScript and TypeScript. By leveraging official Stately.ai documentation, it ensures type-safe implementations with the latest v5 APIs like `setup()` and `createMachine`, facilitating the creation of predictable and maintainable codebases.

Use Cases

  • Modeling complex UI logic: Designing statecharts for multi-step forms or intricate user flows to prevent impossible states and ensure predictable behavior.
  • Actor-based orchestration: Implementing independent entities that communicate via messages for scalable system components and complex service coordination.
  • TypeScript migration and integration: Upgrading legacy XState v4 code to v5 using type-safe patterns, the `setup()` function, and modern TypeScript 5.0+ features.
  • Debugging and visualization: Troubleshooting state transitions, actions, and actor behaviors using the Inspection API and visual modeling principles from Stately.ai.
  • Framework Integration: Connecting XState logic with modern frontend frameworks like React, Vue, or Svelte using recommended v5 patterns.
namexstate
descriptionUse this skill when working with XState v5 - a state management and orchestration library using state machines, statecharts, and the actor model for complex logic in JavaScript/TypeScript applications.

XState v5 Skill

Comprehensive assistance with XState v5 development, generated from official Stately.ai documentation.

IMPORTANT: XState v5 ONLY

This skill covers XState v5 exclusively. DO NOT use XState v4 APIs, documentation, or examples.

  • Always verify documentation URLs contain "xstate" (current docs), not "xstate-v4"
  • When researching, explicitly search for "XState v5" to avoid v4 results
  • XState v5 uses setup() and requires TypeScript 5.0+ - if you see older patterns, it's v4
  • If migrating from v4, consult the v5 migration guide but implement using v5 APIs only

When to Use This Skill

This skill should be triggered when:

  • State machine design: Creating or modeling application logic with state machines/statecharts
  • Actor systems: Implementing the actor model for orchestration and communication
  • XState v5 implementation: Writing code using XState v5 APIs (createMachine, createActor, setup)
  • TypeScript typing: Configuring strong types for state machines with XState v5
  • Actor types: Working with promise, callback, observable, or transition actors
  • Debugging state machines: Troubleshooting state transitions, actions, guards, or actor behavior
  • Migration to v5: Understanding v5 API changes when upgrading from v4 (output will use v5 APIs only)
  • Integration: Connecting XState with React, Vue, Svelte, or other frameworks

Key Concepts

State Machines & Actors

  • State machine: A mathematical model of computation that can be in exactly one state at a time
  • Actor model: A computational model where actors are independent entities that communicate by sending messages
  • Statechart: Enhanced state machine with hierarchy, parallelism, and orthogonality
  • XState v5: Requires TypeScript 5.0+, uses setup() function for type-safe machines

Actor Types in XState

  • State machine actors: Logic represented by finite state machines
  • Promise actors: Actors that represent a single promise
  • Callback actors: Logic defined by callback functions that can send events
  • Observable actors: Actors that represent observable streams (e.g., RxJS)
  • Transition actors: Simple reducer-like actors (similar to Redux reducers)

Quick Reference

1. Simple Counter Machine (Beginner)

Basic state machine with context and actions:

import { createMachine, assign, createActor } from 'xstate';

const countMachine = createMachine({
  context: {
    count: 0,
  },
  on: {
    INC: {
      actions: assign({
        count: ({ context }) => context.count + 1,
      }),
    },
    DEC: {
      actions: assign({
        count: ({ context }) => context.count - 1,
      }),
    },
    SET: {
      actions: assign({
        count: ({ event }) => event.value,
      }),
    },
  },
});

const countActor = createActor(countMachine).start();
countActor.subscribe((state) => {
  console.log(state.context.count);
});

countActor.send({ type: 'INC' }); // logs 1
countActor.send({ type: 'DEC' }); // logs 0

2. Toggle Machine with States (Beginner)

Machine with multiple states and transitions:

import { setup, createActor, assign } from 'xstate';

const machine = setup({
  /* ... */
}).createMachine({
  id: 'toggle',
  initial: 'active',
  context: { count: 0 },
  states: {
    active: {
      entry: assign({
        count: ({ context }) => context.count + 1,
      }),
      on: {
        toggle: { target: 'inactive' },
      },
    },
    inactive: {
      on: {
        toggle: { target: 'active' },
      },
    },
  },
});

const actor = createActor(machine);
actor.subscribe((snapshot) => {
  console.log(snapshot.value);
});

actor.start(); // logs 'active' with context { count: 1 }
actor.send({ type: 'toggle' }); // transitions to 'inactive'

3. Type-Safe Machine with setup() (Intermediate)

Using setup() for strong TypeScript typing:

import { setup } from 'xstate';

const feedbackMachine = setup({
  types: {
    context: {} as { feedback: string },
    events: {} as
      | { type: 'feedback.good' }
      | { type: 'feedback.bad' },
  },
  actions: {
    logTelemetry: () => {
      // Implement telemetry logging
    },
  },
}).createMachine({
  // Machine config with full type inference
  initial: 'idle',
  context: { feedback: '' },
  states: {
    idle: {
      on: {
        'feedback.good': {
          actions: 'logTelemetry',
          target: 'success'
        },
        'feedback.bad': {
          actions: 'logTelemetry',
          target: 'failure'
        }
      }
    },
    success: {},
    failure: {}
  }
});

4. Callback Actor for Event Listeners (Intermediate)

Using callback actors to interface with external systems:

import { createActor, fromCallback, sendTo, setup } from 'xstate';

const resizeLogic = fromCallback(({ sendBack, receive }) => {
  const resizeHandler = (event) => {
    sendBack(event);
  };

  window.addEventListener('resize', resizeHandler);

  const removeListener = () => {
    window.removeEventListener('resize', resizeHandler);
  };

  receive((event) => {
    if (event.type === 'stopListening') {
      console.log('Stopping listening');
      removeListener();
    }
  });

  // Cleanup function
  return () => {
    console.log('Cleaning up');
    removeListener();
  };
});

const machine = setup({
  actors: { resizeLogic }
}).createMachine({
  invoke: {
    src: 'resizeLogic',
  },
});

5. Callback Actor with Input (Intermediate)

Passing input to callback actors:

import { fromCallback, createActor, setup, type EventObject } from 'xstate';

const resizeLogic = fromCallback<EventObject, { defaultSize: number }>(
  ({
    sendBack,
    receive,
    input, // Typed as { defaultSize: number }
  }) => {
    console.log(input.defaultSize); // 100

    // Use input.defaultSize in your logic
    return () => {
      // Cleanup
    };
  }
);

const machine = setup({
  actors: {
    resizeLogic,
  },
}).createMachine({
  invoke: {
    src: 'resizeLogic',
    input: {
      defaultSize: 100,
    },
  },
});

6. Observable Actor with RxJS (Advanced)

Creating observable actors for stream processing:

import { fromObservable, createActor } from 'xstate';
import { interval } from 'rxjs';

const intervalLogic = fromObservable(({ input }) =>
  interval(input.interval)
);

const intervalActor = createActor(intervalLogic, {
  input: { interval: 10_000 },
});

intervalActor.subscribe((snapshot) => {
  console.log(snapshot.context);
});

intervalActor.start();
// logs 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ...
// every 10 seconds

7. Inspection API for Debugging (Advanced)

Using the Inspect API to observe state transitions:

const actor = createActor(machine, {
  inspect: (inspectionEvent) => {
    // type: '@xstate.actor' - when actor is created
    // type: '@xstate.snapshot' - when state updates
    // type: '@xstate.event' - when event is sent
    // type: '@xstate.microstep' - for each transition step
    console.log(inspectionEvent);
  },
});

actor.start();

8. TypeScript Configuration

Required TypeScript setup for XState v5:

{
  "compilerOptions": {
    "strictNullChecks": true,
    "skipLibCheck": true
  }
}

9. Installation Commands

# npm
npm install xstate

# pnpm
pnpm install xstate

# yarn
yarn add xstate

# TypeScript (required: v5.0+)
npm install typescript@latest --save-dev

Reference Files

This skill includes comprehensive documentation in references/:

  • state.md - Complete documentation covering:
    • Observable actors and RxJS integration
    • TypeScript setup and type safety
    • Installation and getting started
    • Callback actors for event handling
    • Cheatsheet with syntax examples
    • Inspection API for debugging
    • State machine actors and capabilities
    • Actor input/output patterns

Use the reference file to access:

  • Detailed API documentation with complete examples
  • TypeScript type helpers (ActorRefFrom, SnapshotFrom, EventFrom)
  • Event assertion patterns for type safety
  • Complete inspection event schemas
  • Actor system architecture patterns

Working with This Skill

For Beginners

Start here:

  1. Review the "Simple Counter Machine" example above
  2. Understand the basic concepts: states, events, transitions, context
  3. Learn the core APIs: createMachine, createActor, assign
  4. Check the cheatsheet section in references/state.md

Key learning path:

  • States and transitions (toggle machine example)
  • Context and actions (counter machine example)
  • Event handling with send()
  • Subscribing to state changes

For Intermediate Users

Focus areas:

  1. Type safety with the setup() function
  2. Actor invocation and communication patterns
  3. Callback actors for external system integration
  4. Input/output patterns for actor data flow

Common tasks:

  • Creating reusable actor logic
  • Implementing guards and actions
  • Passing typed input to actors
  • Managing actor lifecycle (cleanup)

For Advanced Users

Advanced topics:

  1. Observable actors with RxJS integration
  2. Actor system orchestration (parent-child relationships)
  3. Inspection API for comprehensive debugging
  4. Microstep analysis for complex transitions
  5. Custom actor logic creators

Integration patterns:

  • Framework integration (React, Vue, Svelte)
  • Backend state orchestration
  • Event-driven architecture
  • Testing state machines
  • Need type safety? → See "Type-Safe Machine with setup()" example and TypeScript section
  • External events? → Check callback actor examples
  • Debugging issues? → Use Inspection API example and review inspection events
  • Stream data? → See Observable actor with RxJS
  • Quick syntax lookup? → Reference the cheatsheet examples in state.md

TypeScript Support

XState v5 requires TypeScript 5.0 or higher. Key features:

  • setup() function: Strongly types machines, context, events, and actions
  • .types property: Alternative typing method in machine config
  • Type helpers: ActorRefFrom<T>, SnapshotFrom<T>, EventFrom<T>
  • assertEvent(): Type assertion helper for narrowing event types
  • Dynamic parameters: Preferred over direct event access for type safety

Common Patterns

Actor Communication

// Send events between actors
sendTo('childActor', { type: 'message' })

// Receive events in callback actor
receive((event) => {
  if (event.type === 'message') {
    // Handle message
  }
})

Cleanup & Lifecycle

// Return cleanup function from callback actor
return () => {
  // Cleanup resources
  removeEventListeners();
  clearTimers();
};

Type-Safe Event Handling

// Use assertEvent for type narrowing
import { assertEvent } from 'xstate';

actions: {
  handleEvent: ({ event }) => {
    assertEvent(event, 'specificEventType');
    // TypeScript now knows event.type is 'specificEventType'
    console.log(event.specificProperty);
  }
}

Resources

  • Documentation: https://stately.ai/docs/xstate (v5 docs - avoid /xstate-v4/ URLs)
  • Stately Studio: Visual editor and debugging tool for state machines
  • VS Code Extension: XState extension for visual editing and autocomplete

scripts/

Add helper scripts here for common automation tasks.

assets/

Add templates, boilerplate, or example projects here.

Notes

  • This skill covers XState v5 specifically (requires TypeScript 5.0+)
  • All actors in XState are observable
  • The setup() function is the recommended way to create type-safe machines
  • Typegen is not yet available for v5; use setup() or .types instead
  • Use the Inspection API for comprehensive debugging
  • Reference files contain links to original documentation

Updating

To refresh this skill with updated documentation:

  1. Re-run the scraper with the same configuration
  2. The skill will be rebuilt with the latest information