aio-xstate

XState v5 Strict Skill

Environment

• tsc: !tsc --version 2>/dev/null || echo "NOT INSTALLED"

XState v5 ONLY. Requires TypeScript 5.0+. Never use v4 patterns.

Workflow

1. Design first (unless user says skip): produce planning artifacts before code
2. Types first: types.context, types.events, types.input (+ types.output)
3. Implement: setup({...}).createMachine({...}) with all implementations in setup
4. Validate: tsc --noEmit, no any leaks, no string events, no v4 imports

Quick Reference

import { setup, assign, fromPromise, createActor } from "xstate"

const machine = setup({
  types: {
    context: {} as { count: number },
    events: {} as { type: "inc" } | { type: "add"; amount: number },
    input: {} as { initialCount?: number },
  },
  actions: {
    inc: assign({ count: ({ context }) => context.count + 1 }),
    add: assign({
      count: ({ context }, params: { amount: number }) => context.count + params.amount,
    }),
  },
  guards: {
    isPositive: ({ context }) => context.count > 0,
  },
}).createMachine({
  id: "counter",
  context: ({ input }) => ({ count: input.initialCount ?? 0 }),
  initial: "active",
  states: {
    active: {
      on: {
        inc: { actions: "inc" },
        add: {
          actions: {
            type: "add",
            params: ({ event }) => ({ amount: event.amount }),
          },
        },
      },
    },
  },
})

const actor = createActor(machine, { input: { initialCount: 0 } })
actor.subscribe((snapshot) => console.log(snapshot.context.count))
actor.start()
actor.send({ type: "inc" })

Hard Rules

1. setup({...}).createMachine({...}) for all machines
2. All implementations in setup(): actions, guards, actors
3. Typed params: actions/guards take (_, params: { ... }) second arg
4. Event objects only: actor.send({ type: "X" }), never strings
5. No god-machine: unrelated domains = separate actors/machines
6. No state-mirroring booleans: use state nodes for modes, context for data
7. invoke has onError: always handle failure
8. No v4 patterns: no interpret, Machine, cond, send, pure, choose