XState Machine Definition

Define statecharts with createMachine for explicit states, transitions, context, and events

When to Use

• Modeling complex UI flows with multiple states (forms, wizards, authentication)
• Replacing boolean flag soup (

  isLoading && !isError && isSubmitted

  ) with named states
• Building workflows where illegal state transitions must be prevented
• Any feature where a state diagram would clarify the logic

Instructions

1. Define the machine in a

   .machine.ts

   file. Keep it separate from UI components.
2. Start with the types: define

   Context

   (extended state data) and

   Events

   (a discriminated union of all possible events).
3. Use

   createMachine

   with

   id

   ,

   initial

   ,

   context

   , and

   states

   . Each state has

   on

   for transitions.
4. Name states as nouns or adjectives (

   idle

   ,

   loading

   ,

   error

   ), not verbs.
5. Name events as past-tense descriptions of what happened (

   SUBMITTED

   ,

   LOADED

   ,

   ERRORED

   ) or imperative commands (

   SUBMIT

   ,

   RETRY

   ).
6. Use

   target

   for the destination state. Omit

   target

   for self-transitions that only run actions.
7. Keep machines pure — no side effects in the machine definition itself. Use actions and services for effects.

// auth.machine.ts
import { createMachine, assign } from 'xstate';

interface AuthContext {
  user: { id: string; name: string } | null;
  error: string | null;
  retries: number;
}

type AuthEvent =
  | { type: 'LOGIN'; email: string; password: string }
  | { type: 'LOGOUT' }
  | { type: 'RETRY' }
  | { type: 'done.invoke.authenticate'; data: { id: string; name: string } }
  | { type: 'error.platform.authenticate'; data: Error };

const authMachine = createMachine<AuthContext, AuthEvent>({
  id: 'auth',
  initial: 'idle',
  context: {
    user: null,
    error: null,
    retries: 0,
  },
  states: {
    idle: {
      on: {
        LOGIN: 'authenticating',
      },
    },
    authenticating: {
      invoke: {
        id: 'authenticate',
        src: 'authenticateUser',
        onDone: {
          target: 'authenticated',
          actions: assign({ user: (_, event) => event.data, error: null }),
        },
        onError: {
          target: 'error',
          actions: assign({
            error: (_, event) => event.data.message,
            retries: (ctx) => ctx.retries + 1,
          }),
        },
      },
    },
    authenticated: {
      on: {
        LOGOUT: {
          target: 'idle',
          actions: assign({ user: null }),
        },
      },
    },
    error: {
      on: {
        RETRY: {
          target: 'authenticating',
          guard: 'canRetry',
        },
        LOGIN: 'authenticating',
      },
    },
  },
});

export { authMachine };

Details

Context vs state: "State" in XState means the finite state node (idle, loading, error). "Context" is the extended state — arbitrary data that travels with the machine. Use finite states for mode/phase, context for data.

XState v5 changes: If using XState v5, the API shifts to

setup().createMachine()

with a different structure:

import { setup, assign } from 'xstate';

const machine = setup({
  types: {} as {
    context: AuthContext;
    events: AuthEvent;
  },
  guards: { canRetry: ({ context }) => context.retries < 3 },
  actions: { clearUser: assign({ user: null }) },
}).createMachine({
  id: 'auth',
  initial: 'idle',
  context: { user: null, error: null, retries: 0 },
  states: {
    /* ... */
  },
});

State node types:

• atomic

  — leaf node, no child states (default)

• compound

  — has child states (nested)

• parallel

  — all child states active simultaneously

• final

  — terminal state, triggers

  onDone

  in the parent

• history

  — remembers the last active child state

Design principles:

• Every event should be handled in every state, even if the handler is a no-op. Unhandled events are silently ignored, which can mask bugs.
• Draw the state diagram first, code second. XState machines are visual — use Stately.ai or the VS Code extension.
• Prefer fewer top-level states with nested substates over many flat states.

Source

https://stately.ai/docs/machines

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.