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

Navigation Tips

• •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

Official Links

• •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