Xstate

XState v5

Use this skill for state machine and statechart engineering first and API correctness second.

This skill is v5-only. When examples, blog posts, answers, or local code smell v4-ish, translate them rather than mixing versions. Prefer local repo code and official v5 docs over generic memory.

Your job:

• choose between xstate and @xstate/store
• design a sound machine or actor system from messy requirements
• write modern XState v5 TypeScript code in a consistent style
• review, repair, or improve existing XState code
• migrate legacy v4-ish patterns when they appear
• choose the right actor kind and action shape when the problem is not just assign(...) plus fromPromise(...)
• connect machines and actors to @xstate/react, @xstate/vue, @xstate/svelte, or @xstate/solid when needed

First pass

In an existing codebase:

1. Inspect local package.json files and imports. 2. Read nearby machines, stores, actors, and adapter usage. 3. Distinguish between new code, local edits, and migration work before choosing how opinionated to be. 4. Preserve surrounding style by default.

Task mode

Choose a mode before writing code:

• New code: prefer the modern v5 patterns in this skill.
• Local edit: preserve local structure and naming unless the current code is mixed, broken, or cleanup was

requested.

• Migration: prefer the smallest safe translation to v5. Preserve structure and semantics unless broader

normalization was requested.

For migration and local edits, do not introduce setup(...), named implementations, object-form guards/actions, tags, or actor decomposition unless they are required for correctness, significantly reduce local complexity, or were explicitly requested.

Choose the tool

Prefer @xstate/store when the domain is simple event-based state management:

• no meaningful finite modes that need coordination, orchestration, or explicit lifecycle modeling
• no invoked async processes
• no actor communication
• no need for state machine or statechart concepts such as guarded transitions, delayed transitions, parallel states, or

history

Simple fetching or mutation logic can still fit @xstate/store if it does not need machine-level orchestration.

Prefer XState when the domain has one or more of these:

• finite modes that matter to behavior or UI
• async workflows, retries, cancellation, or background processes
• multiple interacting processes or child actors
• explicit guards, delays, tags, or transition rules
• a need to model business process flow, not just update state

If the problem is too simple for a machine, say so plainly and recommend @xstate/store.

Workflow

When requirements are fuzzy:

1. Sketch the machine shape first. 2. Name the important states, events, context, actors, and tags. 3. Call out uncertainty or tradeoffs briefly. 4. Then write the code.

When requirements are already clear, keep the sketch short or implicit and move to code.

Do not over-refactor existing code for conceptual purity. Improve the model where it matters, but preserve working structure when a larger rewrite is not justified.

Modeling questions

Use these questions before writing or revising code:

• What are the finite states? Put modes in states, not in context.
• What belongs in context? Keep only durable data, not derivable booleans or duplicated mode.
• What are the domain events? Prefer meaningful names, often dot-separated, such as form.submitted or

order.confirmed.

• What should be a guard versus a separate branch state?
• What side effects should be invoked actors versus transition actions?
• Can an event carry the needed data instead of stashing temporary relay data in context for a later state?
• Is fromPromise(...) actually the right actor, or is this a callback/subscription protocol that should send events

back over time?

• Should the machine emit events to the surrounding system instead of forcing consumers to infer everything from

context?

• Should a child concern be a spawned/invoked actor instead of more parent complexity?
• Does the parent really need these extra intermediate states, or should a child actor own that internal detail?
• Which states need tags for UI semantics such as 'loading', 'error', or 'dirty'?
• Can the UI use snapshot.matches(...), tags, or snapshot.can(...) instead of extra booleans?

Preferred v5 patterns

For new code, prefer these patterns unless the local codebase has a strong reason not to:

• TypeScript only.
• Prefer setup({...}).createMachine({...}).
• Define named actions, guards, actors, and delays in setup(...).
• Prefer transition objects like { target: 'next' } over shorthand when it improves consistency.
• Prefer arrays for actions, even for a single action, when that keeps the shape consistent.
• Prefer action and guard objects such as { type: 'track' } or { type: 'isValid', params: ... } when the intent is

reusable or named.

• Prefer tags: [] for UI semantics and cross-cutting state meaning.
• Prefer domain-oriented event names; preserve local naming conventions if they are already established.
• Prefer plain functions for derived values instead of storing derivable data in context.
• Prefer event payloads over temporary context relay when one state only needs to pass data to the next step.
• Prefer passing data into named actions and guards via params instead of reaching into event directly.
• Do not treat assign(...) as the only action pattern. For typed reusable logic beyond simple context updates,

consider setup-scoped helpers from a const machineSetup = setup(...) object, such as machineSetup.createAction(...), machineSetup.enqueueActions(...), and machineSetup.emit(...), or named action objects when they fit the behavior better.

• When a named assign(...) action updates multiple context properties, every property updater shares the same params

type. Use one coherent params object for all updated fields, or split the work into separate named actions. Do not mix incompatible params shapes inside one assigner.

• When an implementation must inspect event and the type is not obvious, prefer assertEvent(...) for narrowing.
• Avoid as any and other loose casts in examples and final code unless there is no cleaner local option.
• Choose actor logic intentionally: prefer fromPromise(...) for one request/one result, and prefer fromCallback(...)

for subscriptions, timers, external callbacks, and multi-event protocols that send events back over time.

• Consider emit(...) when the machine should notify the surrounding system directly.
• Keep parent states coarse when possible. If extra intermediate states mainly model an implementation detail, prefer

letting a child actor own that internal behavior.

• If you show multiple files, wire them completely. Include real imports/exports for referenced modules and components,

or keep the example smaller.

Keep event naming consistent. The . in event names is useful and meaningful, including for partial event descriptors and clearer domain grouping. See the official docs on events and transitions and TypeScript narrowing with `assertEvent(...)`.

See references/examples.md for canonical code shapes, references/advanced-patterns.md when the task involves typed actions beyond assign(...), callback actors, emitted events, or persistence/hydration, and references/observables-and-inspection.md for fromObservable(...), inspection, and browser inspector patterns.

UI integration

Prefer letting the machine drive UI behavior:

• use snapshot.matches(...) for finite mode checks
• use tags for semantic checks such as loading, saving, or dirty
• use snapshot.can(...) to drive whether an event is currently valid
• avoid parallel piles of manual booleans that restate machine truth

If a component owns a small local actor, useMachine(...) is often enough.

If an actor is shared, long-lived, or performance-sensitive:

• create or obtain an actor ref once
• read slices with useSelector(...)
• use actor context/provider helpers when the actor is shared across a subtree

See references/adapters.md for concise adapter guidance, and references/react.md for React hook selection, input wiring, nested-state matching, and custom hook patterns.

Review and repair guidance

When reviewing or fixing XState code, look for:

• finite mode stored in context instead of states
• giant machines that should be split into child actors
• side effects hidden in random callbacks or mixed into assigners
• v4 and v5 concepts mixed together in the same machine
• state names and event names that describe UI mechanics instead of domain meaning
• extra booleans that should be replaced by matches(...), tags, or selectors
• missed opportunities to use @xstate/store when the problem is simple
• named assign(...) actions whose property updaters implicitly expect different params shapes

Avoid pushing decomposition too far. Actor boundaries are useful when they improve clarity, ownership, or concurrency. Do not split for its own sake.

Migration

When legacy code is present, translate toward v5 gradually and locally unless the user asked for a broader migration.

Common migration targets include:

• cond -> guard
• schema -> types
• services -> actors
• interpret(...) -> createActor(...)
• old function signatures -> destructured v5 arguments such as ({ context, event })

For migration tasks:

• preserve local structure first
• change only what is needed for correctness, compatibility, or clarity
• do not normalize into the full preferred house style unless the user asked for that
• explain any non-local refactor you choose to make
• do not preserve dead or invalid hook option patterns just because they existed nearby
• when migrating React usage, prefer valid current hook surfaces over trying to smuggle old interpret-style

implementation overrides into useMachine(...)

Use references/v4-to-v5-quick-ref.md for quick translation patterns.

Persistence

When persistence or hydration matters:

• persist snapshots, not just context, unless context-only restore is truly sufficient
• prefer actor.getPersistedSnapshot() for saving machine state
• prefer hydrating with createActor(machine, { snapshot }) or adapter/provider snapshot options where available
• do not hand-roll restoration by guessing the state value plus a partial context blob

See references/advanced-patterns.md for concrete persistence and hydration patterns.

Testing

Do not introduce testing guidance unless the user asks about testing or requests tests.

If they do ask, keep it brief:

• test key transitions and guards
• test happy path and failure path actor behavior
• test the UI against machine state rather than duplicating stateful logic
• mention model-based testing utilities when useful

If a link would help, point them to the XState testing and graph/path generation docs.

Optional tools

Stately Studio and inspection tools can help with design, debugging, and communication, but they are optional. Mention them when the user is designing a machine, wants visualization, or needs better debugging visibility.

• Stately Studio for visual modeling and collaboration
• Inspection API for observing actor systems
• Stately Inspector for visual inspection in running apps

Output format

Prefer this output shape:

1. Short machine sketch if requirements are fuzzy. 2. Code. 3. Brief rationale explaining states, events, context, actors, and tags. 4. Migration notes only if relevant.

Prefer fewer complete files over a larger but partially wired example. Do not sketch extra shell files unless they are fully wired.

See references/examples.md for more canonical examples that can grow over time.

Final self-check

Before you answer, do a quick compile-minded pass:

• every JSX component from another file has a real import
• every imported symbol is actually exported by the shown file
• every send(...) and snapshot.can(...) call uses real event objects
• async work uses actors/fromPromise and invoke.input, not legacy shapes
• if you reference an external helper from the prompt or surrounding system, declare its signature or show enough typed

shape for the example to stand on its own

• migration examples do not pass invalid implementation override objects into hooks just to preserve dead local code
• no placeholder shell files, omitted imports, ..., or pseudocode in code fences that are meant to be runnable

If a complete multi-file answer is getting bulky, remove the shell file and keep the smaller set of files that still demonstrates the pattern correctly.

Adapter Notes

Use this file for brief framework-specific guidance after the machine design is already clear.

The concepts are the same across adapters:

• create or obtain an actor ref
• read slices of snapshot state with selectors when possible
• send events to the actor
• avoid duplicating machine truth in component-local booleans

React

• Use useMachine(machine) when the component owns a local actor.
• Prefer createActorContext(...), useActorRef(...), and useSelector(...) when the actor is shared or when you want finer-grained subscriptions.
• Prefer UI checks like snapshot.matches(...), snapshot.hasTag(...), and snapshot.can(...).
• See react.md for a deeper hook-selection table, input wiring, nested-state matching, and the custom hook pattern.

Vue

• Use useMachine(machine) for simple component-local ownership.
• Prefer useActorRef(...) and useSelector(...) when working with shared actors or more selective subscriptions.
• Keep template conditionals driven by snapshot state or tags.

Svelte

• Use useMachine(machine) for local ownership.
• Prefer actor refs plus useSelector(...) when you need shared ownership or selective updates.
• Keep derived UI state close to the machine snapshot rather than duplicating it in separate stores.

Solid

• Use useMachine(machine) for local ownership.
• Prefer useActorRef(...) and useSelector(...) when an actor is shared or when you want tighter subscription control.
• Keep signals derived from actor snapshot slices instead of rebuilding mode booleans manually.

Heuristic

Prefer useMachine(...) when:

• the actor is local to one component
• ownership is simple
• rendering pressure is low

Prefer actor ref + selector patterns when:

• the actor is shared across a subtree
• multiple components read different slices
• you want clearer ownership boundaries
• you want to avoid broad rerenders

Advanced XState v5 Patterns

Use this reference when the task involves any of these:

• typed actions beyond plain assign(...)
• deciding between fromPromise(...) and fromCallback(...)
• machine-emitted events
• persistence and hydration
• reducing over-modeled parent machines

Typed actions beyond assign(...)

LLMs often act like assign(...) is the only useful action. It is not.

For typed reusable action logic, prefer setup-scoped helpers from a const machineSetup = setup(...) object when they make the behavior clearer:

• machineSetup.createAction(...) for typed custom actions
• machineSetup.enqueueActions(...) when one transition should enqueue several actions conditionally
• machineSetup.emit(...) when the machine should emit an event to the surrounding system
• machineSetup.assign(...), machineSetup.raise(...), machineSetup.sendTo(...), etc. when you want type-bound built-ins

Minimal pattern:

import { setup } from 'xstate';

const machineSetup = setup({
  types: {} as {
    context: { count: number };
    events: { type: 'count.incremented'; value: number } | { type: 'count.flushed' };
    emitted: { type: 'count.changed'; count: number };
  }
});

const increment = machineSetup.assign({
  count: ({ context, event }) =>
    event.type === 'count.incremented' ? context.count + event.value : context.count
});

const raiseFlush = machineSetup.raise({ type: 'count.flushed' });

const emitChanged = machineSetup.emit(({ context }) => ({
  type: 'count.changed',
  count: context.count
}));

const flushIfNeeded = machineSetup.enqueueActions(({ context, enqueue }) => {
  if (context.count > 10) {
    enqueue(raiseFlush);
  }
});

Local anchors:

• setup-scoped typed helpers: /Users/davidkpiano/Code/xstate/packages/core/CHANGELOG.md
• enqueueActions(...) in a real machine: /Users/davidkpiano/Code/xstate/examples/tiles/src/tilesMachine.ts

Prefer event payloads over context relay

If state A only stores data so state B can use it immediately, ask whether that data should just travel on an event.

Prefer:

• event carries the payload the next transition or actor needs
• child actor input comes from the triggering event when that is the natural source

Be careful about:

• storing temporary request payloads in context solely so onDone or a later state can read them
• adding context fields that duplicate transient protocol data
• storing raw transport artifacts like latestChunk, callback payloads, or response wrappers when the machine only needs a derived durable value such as progress

Context should hold durable state, not every hop in the protocol.

Choosing the right actor kind

Do not default to fromPromise(...).

Prefer fromPromise(...) when:

• one request produces one result or one failure
• the actor does not need to push multiple events over time
• the machine genuinely wants onDone / onError

Prefer fromCallback(...) when:

• the actor wraps subscriptions, timers, DOM listeners, sockets, or external callbacks
• the actor needs to send multiple events back over time
• forcing everything into onDone / onError makes the machine awkward

When writing callback-actor examples:

• declare the external callback API shape if it is not already defined in the snippet
• type the callback payload instead of leaving msg, chunk, or err as implicit any
• prefer sending domain events like upload.progress or timer.ticked back to the parent
• keep only durable results in context; avoid storing raw callback payloads unless the machine truly needs them later

Local anchors:

• callback actor with recurring events: /Users/davidkpiano/Code/xstate/examples/workflow-check-inbox/main.ts
• callback actor for ticking input: /Users/davidkpiano/Code/xstate/examples/stopwatch/src/stopwatchMachine.ts

Minimal upload-style callback pattern:

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

type UploadMessage =
  | { type: 'progress'; loaded: number; total: number }
  | { type: 'complete' }
  | { type: 'error'; error: unknown };

declare function startUploadAndListen(
  uploadId: string,
  onMessage: (message: UploadMessage) => void
): () => void;

const machineSetup = setup({
  types: {} as {
    context: {
      uploadId: string | null;
      progress: number;
      error: string | null;
    };
    events:
      | { type: 'upload.started'; uploadId: string }
      | { type: 'upload.progress'; loaded: number; total: number }
      | { type: 'upload.completed' }
      | { type: 'upload.failed'; error: string };
  },
  actors: {
    upload: fromCallback<
      { type: 'upload.progress'; loaded: number; total: number }
      | { type: 'upload.completed' }
      | { type: 'upload.failed'; error: string },
      { uploadId: string }
    >(({ input, sendBack }) => {
      return startUploadAndListen(input.uploadId, (message) => {
        if (message.type === 'progress') {
          sendBack({
            type: 'upload.progress',
            loaded: message.loaded,
            total: message.total
          });
          return;
        }
        if (message.type === 'complete') {
          sendBack({ type: 'upload.completed' });
          return;
        }
        sendBack({ type: 'upload.failed', error: String(message.error) });
      });
    })
  }
});

export const uploadMachine = machineSetup.createMachine({
  context: {
    uploadId: null,
    progress: 0,
    error: null
  },
  initial: 'idle',
  states: {
    idle: {
      on: {
        'upload.started': {
          target: 'uploading',
          actions: assign({ uploadId: ({ event }) => event.uploadId })
        }
      }
    },
    uploading: {
      invoke: {
        src: 'upload',
        input: ({ context }) => ({ uploadId: context.uploadId! })
      },
      on: {
        'upload.progress': {
          actions: assign({
            progress: ({ event }) =>
              Math.round((event.loaded / event.total) * 100)
          })
        },
        'upload.completed': { target: 'done' },
        'upload.failed': {
          target: 'failed',
          actions: assign({ error: ({ event }) => event.error })
        }
      }
    },
    done: {},
    failed: {}
  }
});

Emitted events

Machines can emit events. This is useful when the machine is driving a larger system and should announce something meaningful outward, instead of forcing every consumer to poll context or infer behavior indirectly.

Prefer emitted events when:

• the machine is modeling a process that should notify the outside world
• the notification is part of the domain, not just UI plumbing
• the alternative is stuffing extra bookkeeping into context for others to watch

Use types.emitted plus machineSetup.emit(...) for typed emitted events.

Local anchor:

• typed emitted events and machineSetup.emit(...): /Users/davidkpiano/Code/xstate/packages/core/CHANGELOG.md

Avoid over-modeling the parent machine

LLMs often over-expand the statechart.

Prefer coarse parent states when:

• the parent only cares about a higher-level mode
• an invoked/spawned child can own transient internal detail
• extra parent states mainly represent implementation noise

Do not split aggressively just for conceptual purity. The goal is a sturdier model, not the maximum number of actors and states.

Persistence and hydration

Prefer snapshot persistence over hand-rolled state reconstruction.

Canonical pattern:

import { createActor } from 'xstate';
import { authMachine } from './authMachine';

const persisted = loadPersistedSnapshot();

const actor = createActor(authMachine, {
  snapshot: persisted
});

actor.subscribe(() => {
  savePersistedSnapshot(actor.getPersistedSnapshot());
});

In UI adapters, prefer provider or hook options that accept a persisted snapshot when available rather than rebuilding state manually.

Be careful about older examples that use state: in actor options. For current v5 code, prefer snapshot: when hydrating persisted machine state.

For migration or repair tasks, do not keep dead implementation override objects alive by passing them into useMachine(...) if the current hook does not accept them. Either move real implementations into setup(...)/machine config or remove dead overrides if they are unused.

Local anchors:

• persisted snapshot save/restore flow: /Users/davidkpiano/Code/xstate/examples/mongodb-persisted-state/main.ts
• persisted snapshot in an API workflow example: /Users/davidkpiano/Code/xstate/examples/express-workflow/index.ts
• React adapter tests using snapshot hydration: /Users/davidkpiano/Code/xstate/packages/xstate-react/test/createActorContext.test.tsx

XState v5 Examples

This file holds expandable canonical examples for the skill. Keep the examples opinionated and small enough to be reusable, but grow this file over time as recurring patterns emerge.

Machine with setup(...)

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

export const feedbackMachine = setup({
  types: {} as {
    context: {
      feedback: string;
    };
    events:
      | { type: 'feedback.good' }
      | { type: 'feedback.bad' }
      | { type: 'feedback.changed'; value: string }
      | { type: 'feedback.submitted' }
      | { type: 'feedback.restarted' };
  },
  guards: {
    hasFeedback: ({ context }) => context.feedback.trim().length > 0
  },
  actions: {
    updateFeedback: assign({
      feedback: (_, params: { value: string }) => params.value
    }),
    clearFeedback: assign({
      feedback: () => ''
    }),
    logSubmission: ({ event }) => {
      assertEvent(event, 'feedback.submitted');
      console.log('submitted feedback');
    })
  }
}).createMachine({
  context: {
    feedback: ''
  },
  initial: 'prompt',
  states: {
    prompt: {
      on: {
        'feedback.good': {
          target: 'thanks'
        },
        'feedback.bad': {
          target: 'form'
        }
      }
    },
    form: {
      tags: ['editable'],
      on: {
        'feedback.changed': {
          actions: [
            {
              type: 'updateFeedback',
              params: ({ event }) => ({ value: event.value })
            }
          ]
        },
        'feedback.submitted': [
          {
            guard: { type: 'hasFeedback' },
            target: 'thanks',
            actions: [{ type: 'logSubmission' }]
          }
        ]
      }
    },
    thanks: {
      tags: ['completed'],
      on: {
        'feedback.restarted': {
          target: 'prompt',
          actions: [{ type: 'clearFeedback' }]
        }
      }
    }
  }
});

Shared actor with React

import { createActorContext } from '@xstate/react';
import { feedbackMachine } from './feedbackMachine';

const FeedbackContext = createActorContext(feedbackMachine);

export function FeedbackProvider(props: { children: React.ReactNode }) {
  return <FeedbackContext.Provider>{props.children}</FeedbackContext.Provider>;
}

export function FeedbackForm() {
  const actorRef = FeedbackContext.useActorRef();
  const canSubmit = FeedbackContext.useSelector((snapshot) =>
    snapshot.can({ type: 'feedback.submitted' })
  );
  const isEditable = FeedbackContext.useSelector((snapshot) =>
    snapshot.hasTag('editable')
  );

  if (!isEditable) {
    return null;
  }

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        actorRef.send({ type: 'feedback.submitted' });
      }}
    >
      <textarea
        onChange={(event) => {
          actorRef.send({
            type: 'feedback.changed',
            value: event.target.value
          });
        }}
      />
      <button disabled={!canSubmit}>Submit</button>
    </form>
  );
}

Shared async auth actor with React

When one actor is shared across a subtree, prefer a provider plus useSelector(...).

If a named assign(...) action updates multiple properties, use one params object that contains every field that action needs.

// authMachine.ts
import { assign, assertEvent, fromPromise, setup } from 'xstate';

type User = { id: string; email: string; name: string };
type Session = { token: string; expiresAt: number };

export const authMachine = setup({
  types: {} as {
    context: {
      user: User | null;
      session: Session | null;
      error: string | null;
    };
    events:
      | { type: 'auth.login'; email: string; password: string }
      | { type: 'auth.logout' }
      | { type: 'auth.refresh' };
  },
  actors: {
    login: fromPromise(
      async ({ input }: { input: { email: string; password: string } }) => {
        const res = await fetch('/api/auth/login', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(input)
        });

        if (!res.ok) {
          throw new Error('Login failed');
        }

        return (await res.json()) as { user: User; session: Session };
      }
    ),
    refreshSession: fromPromise(async () => {
      const res = await fetch('/api/auth/refresh', { method: 'POST' });

      if (!res.ok) {
        throw new Error('Refresh failed');
      }

      return (await res.json()) as { session: Session };
    })
  },
  actions: {
    setAuth: assign({
      user: (_, params: { user: User; session: Session }) => params.user,
      session: (_, params: { user: User; session: Session }) => params.session,
      error: () => null
    }),
    setSession: assign({
      session: (_, params: { session: Session }) => params.session
    }),
    setError: assign({
      error: (_, params: { message: string }) => params.message
    }),
    clearAuth: assign({
      user: () => null,
      session: () => null,
      error: () => null
    })
  }
}).createMachine({
  id: 'auth',
  context: {
    user: null,
    session: null,
    error: null
  },
  initial: 'signedOut',
  states: {
    signedOut: {
      on: {
        'auth.login': { target: 'signingIn' }
      }
    },
    signingIn: {
      tags: ['loading'],
      invoke: {
        src: 'login',
        input: ({ event }) => {
          assertEvent(event, 'auth.login');

          return {
            email: event.email,
            password: event.password
          };
        },
        onDone: {
          target: 'signedIn',
          actions: [
            {
              type: 'setAuth',
              params: ({ event }) => ({
                user: event.output.user,
                session: event.output.session
              })
            }
          ]
        },
        onError: {
          target: 'signedOut',
          actions: [
            {
              type: 'setError',
              params: ({ event }) => ({
                message: event.error instanceof Error ? event.error.message : 'Login failed'
              })
            }
          ]
        }
      }
    },
    signedIn: {
      on: {
        'auth.logout': {
          target: 'signedOut',
          actions: [{ type: 'clearAuth' }]
        },
        'auth.refresh': { target: 'refreshing' }
      }
    },
    refreshing: {
      tags: ['loading'],
      invoke: {
        src: 'refreshSession',
        onDone: {
          target: 'signedIn',
          actions: [
            {
              type: 'setSession',
              params: ({ event }) => ({
                session: event.output.session
              })
            }
          ]
        },
        onError: {
          target: 'signedOut',
          actions: [
            {
              type: 'setError',
              params: ({ event }) => ({
                message: event.error instanceof Error ? event.error.message : 'Refresh failed'
              })
            },
            { type: 'clearAuth' }
          ]
        }
      }
    }
  }
});

// AuthContext.tsx
import { createActorContext } from '@xstate/react';
import { authMachine } from './authMachine';

export const AuthContext = createActorContext(authMachine);

export function AuthProvider(props: { children: React.ReactNode }) {
  return <AuthContext.Provider>{props.children}</AuthContext.Provider>;
}

// Navbar.tsx
import { AuthContext } from './AuthContext';

export function Navbar() {
  const actorRef = AuthContext.useActorRef();
  const userName = AuthContext.useSelector((snapshot) => snapshot.context.user?.name ?? null);
  const isSignedIn = AuthContext.useSelector((snapshot) => snapshot.matches('signedIn'));

  return (
    <nav>
      {isSignedIn ? (
        <>
          <span>{userName}</span>
          <button onClick={() => actorRef.send({ type: 'auth.logout' })}>Logout</button>
        </>
      ) : (
        <span>Signed out</span>
      )}
    </nav>
  );
}

// SettingsPage.tsx
import { AuthContext } from './AuthContext';

export function SettingsPage() {
  const actorRef = AuthContext.useActorRef();
  const user = AuthContext.useSelector((snapshot) => snapshot.context.user);
  const isLoading = AuthContext.useSelector((snapshot) => snapshot.hasTag('loading'));

  if (!user) {
    return <p>Please sign in.</p>;
  }

  return (
    <section>
      <p>{user.email}</p>
      <button
        disabled={isLoading}
        onClick={() => actorRef.send({ type: 'auth.refresh' })}
      >
        {isLoading ? 'Refreshing…' : 'Refresh session'}
      </button>
    </section>
  );
}

// BillingPage.tsx
import { AuthContext } from './AuthContext';

export function BillingPage() {
  const session = AuthContext.useSelector((snapshot) => snapshot.context.session);
  const isSignedIn = AuthContext.useSelector((snapshot) => snapshot.matches('signedIn'));

  if (!isSignedIn || !session) {
    return <p>Billing is unavailable while signed out.</p>;
  }

  return (
    <section>
      <p>Session expires at: {new Date(session.expiresAt).toLocaleString()}</p>
    </section>
  );
}

// App.tsx
import { AuthProvider } from './AuthContext';
import { BillingPage } from './BillingPage';
import { Navbar } from './Navbar';
import { SettingsPage } from './SettingsPage';

export function App() {
  return (
    <AuthProvider>
      <Navbar />
      <SettingsPage />
      <BillingPage />
    </AuthProvider>
  );
}

Prefer @xstate/store for simple domains

Use a store when the domain is just event-based state updates without meaningful modes or actors.

import { createStore } from '@xstate/store';

export const preferencesStore = createStore({
  context: {
    theme: 'light' as 'light' | 'dark',
    compactMode: false
  },
  on: {
    'preferences.themeChanged': (
      context,
      event: { value: 'light' | 'dark' }
    ) => ({
      ...context,
      theme: event.value
    }),
    'preferences.compactModeToggled': (context) => ({
      ...context,
      compactMode: !context.compactMode
    })
  }
});

Migration notes example

Before

const machine = createMachine({
  schema: {
    context: {} as { count: number },
    events: {} as { type: 'inc' } | { type: 'dec' }
  },
  on: {
    inc: {
      cond: (context) => context.count < 10,
      actions: assign({
        count: (context) => context.count + 1
      })
    }
  }
});

After

const machine = setup({
  types: {} as {
    context: { count: number };
    events: { type: 'inc' } | { type: 'dec' };
  },
  guards: {
    canIncrement: ({ context }) => context.count < 10
  },
  actions: {
    increment: assign({
      count: ({ context }) => context.count + 1
    })
  }
}).createMachine({
  context: {
    count: 0
  },
  on: {
    inc: [
      {
        guard: { type: 'canIncrement' },
        actions: [{ type: 'increment' }]
      }
    ]
  }
});

Observables And Inspection

Use this reference when the task involves any of these:

• fromObservable(...) or RxJS-backed actors
• inspection/debugging of actor systems
• browser inspector wiring in app code

Observable actors

Prefer fromObservable(...) when the actor naturally wraps a stream of values from an observable source.

Use it when:

• the source is already an observable
• values arrive over time
• the actor should subscribe/unsubscribe with actor lifecycle

Prefer fromCallback(...) instead when the source is a callback/listener API rather than an observable.

Local anchor:

• typed fromObservable(...) example: /Users/davidkpiano/Code/xstate/packages/core/CHANGELOG.md

Minimal shape:

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

type Output = number;
type Input = { period?: number };

const tickerLogic = fromObservable<Output, Input>(({ input }) => {
  return interval(input.period ?? 1000);
});

const actor = createActor(tickerLogic, {
  input: { period: 500 }
});

Inspection API

When debugging actor systems programmatically, use actor.system.inspect(...).

This is useful when:

• you need structured transition/event/snapshot visibility
• you want to log or capture inspection events in tests or tooling
• you want lower-level visibility than ordinary subscriptions

It accepts either a function or an observer and returns a subscription.

Local anchor:

• actor.system.inspect(...) usage and unsubscribe behavior: /Users/davidkpiano/Code/xstate/packages/core/test/inspect.test.ts

Minimal shape:

import { createActor, createMachine } from 'xstate';

const actor = createActor(createMachine({}));

const sub = actor.system.inspect((inspectionEvent) => {
  console.log(inspectionEvent.type);
});

actor.start();

sub.unsubscribe();

Browser inspector

When the user wants visual debugging in an app, prefer @statelyai/inspect with createBrowserInspector(...).

Local anchor:

• React template wiring: /Users/davidkpiano/Code/xstate/templates/react-ts/src/App.tsx

Minimal shape:

import { useMachine } from '@xstate/react';
import { createBrowserInspector } from '@statelyai/inspect';
import { feedbackMachine } from './feedbackMachine';

const { inspect } = createBrowserInspector({
  autoStart: false
});

export function Feedback() {
  const [snapshot, send] = useMachine(feedbackMachine, {
    inspect
  });

  return (
    <button onClick={() => send({ type: 'restart' })}>
      {snapshot.matches('closed') ? 'Restart' : 'Send'}
    </button>
  );
}

Rule of thumb

• fromPromise(...): one request, one result
• fromCallback(...): callback/listener protocol, many events
• fromObservable(...): real observable stream
• actor.system.inspect(...): programmatic visibility
• createBrowserInspector(...): visual/debug UI visibility

React Integration

Use this reference after the machine design is settled and you need React-specific wiring detail beyond references/adapters.md.

For the shared-actor pattern with createActorContext(...), see references/examples.md. For inspector wiring (createBrowserInspector(...)), see references/observables-and-inspection.md.

Hook surface

Prefer useActorRef + useSelector over useActor when the actor is shared or when broad rerenders matter. useActor is best reserved for small child components that legitimately need [snapshot, send] against a passed-in ref.

Passing initial context via input

When the machine uses input to seed context, pass it through useMachine:

import { useMachine } from '@xstate/react';
import { assign, setup } from 'xstate';

const counterMachine = setup({
  types: {} as {
    context: { count: number };
    input: { initialCount: number };
    events: { type: 'count.incremented' };
  }
}).createMachine({
  context: ({ input }) => ({ count: input.initialCount }),
  on: {
    'count.incremented': {
      actions: assign({ count: ({ context }) => context.count + 1 })
    }
  }
});

export function Counter({ initialCount }: { initialCount: number }) {
  const [snapshot, send] = useMachine(counterMachine, {
    input: { initialCount }
  });

  return (
    <button onClick={() => send({ type: 'count.incremented' })}>
      {snapshot.context.count}
    </button>
  );
}

Prefer input over reading props inside assign(...). Context is seeded once from input; later prop changes should be modeled as events.

Matching nested states

snapshot.matches(...) accepts both dot-string and object forms for hierarchical states. Both are valid; pick whichever reads more clearly locally.

if (snapshot.matches('processing.validating')) { /* ... */ }
if (snapshot.matches({ processing: 'confirming' })) { /* ... */ }

For parallel states, use the object form for the specific region you care about, and prefer tags when several regions should answer a single UI question like "is anything loading?".

Snapshot-driven UI

Prefer driving JSX directly from the snapshot and actor, not from duplicated local state:

function AuthFlow() {
  const [snapshot, send] = useMachine(authMachine);

  if (snapshot.hasTag('loading')) return <LoadingSpinner />;
  if (snapshot.matches('authenticated')) return <Dashboard user={snapshot.context.user} />;
  if (snapshot.matches('error')) {
    return (
      <ErrorDisplay
        message={snapshot.context.error}
        onRetry={() => send({ type: 'auth.retried' })}
      />
    );
  }

  return (
    <LoginForm
      canSubmit={snapshot.can({ type: 'auth.login', email: '', password: '' })}
      onSubmit={(email, password) => send({ type: 'auth.login', email, password })}
    />
  );
}

Reach for snapshot.can(...) for enablement checks on buttons and inputs, not extra booleans in context.

Custom hook pattern

When a component tree repeatedly pulls the same slices from a machine, a thin wrapper hook can keep the call sites small without duplicating machine truth. Keep the wrapper close to derived values and event helpers; do not let it accumulate component state.

import { useMachine } from '@xstate/react';
import { authMachine } from './authMachine';

export function useAuth() {
  const [snapshot, send, actorRef] = useMachine(authMachine);

  return {
    isAuthenticated: snapshot.matches('signedIn'),
    isLoading: snapshot.hasTag('loading'),
    user: snapshot.context.user,
    error: snapshot.context.error,
    login: (email: string, password: string) =>
      send({ type: 'auth.login', email, password }),
    logout: () => send({ type: 'auth.logout' }),
    actorRef,
    snapshot
  };
}

Prefer this pattern only for locally owned actors. For shared actors, build the same ergonomics with createActorContext(...) plus useSelector(...) so that reads are selective.

Ownership heuristic

• Component-local actor: useMachine(...).
• Shared actor across a subtree: createActorContext(...) + useSelector(...) (see references/examples.md).
• Actor handed down as a prop or ref: useActor(actorRef) for small leaves, or useSelector(actorRef, ...) when rerender pressure matters.
• Send-only component: useActorRef(...) so the component does not subscribe.

XState v4 to v5 Quick Reference

Use this file when you encounter older XState code and need a fast translation path without turning the task into a full migration project.

Default to the smallest safe translation. Preserve local structure unless the user asked for broader normalization.

Core renames

• cond -> guard
• schema -> types
• services -> actors
• interpret(machine) -> createActor(machine)

Prefer v5 argument style

Prefer destructured arguments:

guard: ({ context, event }) => context.count > 0

instead of older positional signatures:

cond: (context, event) => context.count > 0

Prefer setup(...)

For new code or explicit normalization, prefer:

const machine = setup({
  actions: {
    save: () => {
      // ...
    }
  },
  guards: {
    isValid: ({ context }) => context.ready
  },
  actors: {
    loadUser: fromPromise(async () => {
      // ...
    })
  }
}).createMachine({
  // ...
});

This gives a single place for named actions, guards, actors, and delays.

For small migration tasks, you do not need to introduce setup(...) if a more local v5 translation is clearer and safer.

Transition object shapes

Prefer explicit transition objects:

on: {
  submit: {
    target: 'saving',
    actions: [{ type: 'trackSubmit' }]
  }
}

If you are only fixing a local issue in an older file, preserve nearby style unless the user asked for migration.

Invocation

v4 code often uses older service patterns. In v5, prefer named actors:

invoke: {
  src: 'loadUser'
}

with implementations defined in setup({ actors: ... }).

Actor creation

Prefer:

const actor = createActor(machine);
actor.start();

instead of:

const service = interpret(machine).start();

Typing

Prefer types over schema:

types: {} as {
  context: { count: number };
  events: { type: 'increment' } | { type: 'reset' };
}

Guard and action objects

Prefer object forms when the behavior is named or parameterized:

guard: { type: 'hasPermission', params: { role: 'admin' } }
actions: [{ type: 'track', params: { eventName: 'form.submitted' } }]

Preserve scope

Do not force a full v4 -> v5 rewrite when the user asked for a small bug fix or local migration. Translate only the touched area unless:

• the current code is broken due to mixed concepts
• the user explicitly asked for migration
• a local refactor is the simplest safe fix