XState v5 Developer Guide

This skill provides comprehensive guidelines, patterns, and best practices for working with the XState v5 ecosystem in this project, including:

• XState State Machines - Finite state machines and actors for complex application logic
• @xstate/store - Simple event-driven stores for lightweight state management
• XState + TanStack Query - Integration patterns for data fetching orchestration

Quick Reference

Use Case	Tool	Reference
Complex state flows, guards, hierarchical states	XState Machines	references/machine-patterns.md
Simple event-driven state, atoms, undo/redo	@xstate/store	references/store-patterns.md
Data fetching with state orchestration	XState + TanStack Query	references/query-patterns.md

Core Principles

XState State Machines

• Explicit States: Model application logic as explicit finite states and events
• Actor Model: Embrace the actor model for complex orchestration
• Impossible States: Use statecharts to eliminate impossible states
• Declarative Thinking: Think declaratively about state transitions
• Visualization: Use Stately Editor for visual machine creation and debugging

@xstate/store

• Event-Driven Updates: Use events for all state updates (never direct mutations)
• Keep Stores Simple: Focus on data management, not complex logic
• Optimized Subscriptions: Leverage selectors for efficient state access
• Reactive State: Use atoms for composable, reactive state
• Upgrade Path: Migrate to XState machines when complexity grows

XState + TanStack Query Integration

• XState for Orchestration: Use XState machines for workflow orchestration
• TanStack Query for Data: Use TanStack Query for data fetching and caching
• Actors as Bridges: Wrap Query operations as XState actors
• Cache Updates in Mutations: Keep query cache updates in mutation callbacks

---

XState State Machines

Creating a Machine with setup() API

Always use the setup() API for type-safe machines:

import { setup, createActor } from 'xstate';

export enum CounterEventType {
  INCREMENT = 'increment',
  DECREMENT = 'decrement',
}

const counterMachineSetup = setup({
  types: {
    context: {} as { count: number },
    events: {} as
      | { type: CounterEventType.INCREMENT }
      | { type: CounterEventType.DECREMENT },
    input: {} as { initialCount: number },
  },
  guards: {
    isPositive: ({ context }) => context.count > 0,
  },
});

// Define actions OUTSIDE setup using type-bound helpers
const incrementCount = counterMachineSetup.assign({
  count: ({ context }) => context.count + 1,
});

export const counterMachine = counterMachineSetup.createMachine({
  id: 'counter',
  context: ({ input }) => ({ count: input.initialCount }),
  initial: 'active',
  states: {
    active: {
      on: {
        [CounterEventType.INCREMENT]: {
          actions: incrementCount,
        },
      },
    },
  },
});

React Integration

Use useMachine() for component-scoped machines and .provide() for action overrides:

import { useMachine } from '@xstate/react';
import { useMemo } from 'react';

function Counter({ onExternalAction }) {
  const machine = useMemo(
    () =>
      counterMachine.provide({
        actions: {
          logEvent: () => onExternalAction(),
        },
      }),
    [onExternalAction]
  );

  const [state, send] = useMachine(machine);

  return (
    <button onClick={() => send({ type: CounterEventType.INCREMENT })}>
      Count: {state.context.count}
    </button>
  );
}

For detailed patterns: See references/machine-patterns.md

---

@xstate/store

Creating a Store

Define stores with clear initial context and event-based transitions:

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

const userStore = createStore({
  context: {
    user: null as { id: string; name: string } | null,
    isLoading: false,
    error: null as string | null,
  },
  on: {
    setUser: (context, event: { user: { id: string; name: string } }) => ({
      ...context, // Always spread to preserve other properties
      user: event.user,
      error: null,
    }),
    setLoading: (context, event: { isLoading: boolean }) => ({
      ...context,
      isLoading: event.isLoading,
    }),
  },
});

// Use the trigger API for type-safe event sending
userStore.trigger.setUser({ user: { id: '1', name: 'John' } });

React Integration

import { useSelector, useStore } from '@xstate/store/react';

function Counter() {
  const store = useStore({
    context: { count: 0 },
    on: {
      increment: (context, event: { by: number }) => ({
        ...context,
        count: context.count + event.by,
      }),
    },
  });
  const count = useSelector(store, (state) => state.context.count);
  return <button onClick={() => store.trigger.increment({ by: 1 })}>{count}</button>;
}

Undo/Redo Pattern

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

const editorStore = createStore(
  undoRedo({
    context: { text: '' },
    on: {
      insertText: (context, event: { text: string }) => ({
        ...context,
        text: context.text + event.text,
      }),
    },
  })
);

editorStore.trigger.undo();
editorStore.trigger.redo();

For detailed patterns: See references/store-patterns.md

---

XState + TanStack Query Integration

Query Subscriptions with QueryObserver

Use fromCallback with QueryObserver for reactive subscriptions:

import { fromCallback } from "xstate";
import { QueryObserver, type QueryClient } from "@tanstack/react-query";

const subscribeToQuery = fromCallback(({ input, sendBack }) => {
  const { queryClient, entityId } = input as {
    queryClient: QueryClient;
    entityId: string;
  };

  const observer = new QueryObserver(queryClient, {
    queryKey: ["data", entityId],
    queryFn: async () => { /* fetch logic */ },
  });

  const unsubscribe = observer.subscribe((result) => {
    if (result.data) {
      sendBack({ type: "REMOTE_UPDATE", data: result.data });
    }
  });

  // Emit current result immediately
  const currentResult = observer.getCurrentResult();
  if (currentResult.data) {
    sendBack({ type: "REMOTE_UPDATE", data: currentResult.data });
  }

  return () => unsubscribe();
});

Mutations with useMutation

Wrap useMutation hooks as fromPromise actors and provide via .provide():

const machine = useMemo(
  () =>
    createDataMachine().provide({
      actors: {
        saveData: fromPromise(async ({ input }) => {
          return await saveMutation.mutateAsync(input.data);
        }),
      },
    }),
  [saveMutation]
);

For detailed patterns: See references/query-patterns.md

---

Essential Patterns (All Tools)

1. Use setup() for all machines - provides superior type inference
2. Use enums for event types - UPPER_SNAKE_CASE convention
3. Define actions outside setup() - use type-bound helpers like setup().assign()
4. Use enqueueActions() for sequential actions - group related actions together
5. Use .provide() for React integration - override actions with external methods
6. Initialize context from input - use function form for dynamic initialization
7. Always spread ...context in stores - preserve other properties
8. Clean up subscriptions - return cleanup functions from callback actors

---

When to Use Each Tool

Use XState State Machines When:

• Need finite states with specific transitions
• Need guards and conditional transition logic
• Need invoked actors for async orchestration
• Need hierarchical or parallel states
• Building complex multi-step workflows

Use @xstate/store When:

• Simple global or local state management
• Event-driven state updates without complex flows
• Need undo/redo functionality
• Want a lightweight alternative with upgrade path to XState

Use XState + TanStack Query When:

• Need to orchestrate data fetching with UI state
• Building real-time features with cache synchronization
• Managing complex async workflows with server state

---

Common Pitfalls to Avoid

All XState Tools

• Don't use generic parameters; use setup() instead
• Don't define actions inside setup(); define them outside using type-bound helpers
• Don't use string literals for event types; use enums instead
• Don't mutate context directly; always use assign() or return new objects
• Don't make guards impure or with side effects
• Don't use deprecated v4 APIs (interpret(), cond, etc.)
• Don't forget to .start() actors

@xstate/store Specific

• Never forget to spread ...context in returns
• Never subscribe without cleanup
• Never use stores for complex state machines (migrate to XState)

TanStack Query Integration

• Don't create QueryObserver outside callback actors
• Don't update query cache inside machine actions
• Don't pass mutation hooks directly to actors (wrap in fromPromise)
• Don't access QueryClient from closure; pass through context

---

Validation Checklist

Before finishing any task involving XState ecosystem:

For State Machines

• Machine uses setup() API for type safety
• Event types are defined using enums
• Actions are defined outside setup() using type-bound helpers
• Context is initialized from input using function form
• Guards are pure functions without side effects
• React components use useMachine() or useActorRef()

For @xstate/store

• Always spread ...context in transition return values
• Use trigger API for type-safe event sending
• Create selectors for optimized subscriptions
• Clean up subscriptions in React components

For TanStack Query Integration

• QueryObserver subscriptions are wrapped in fromCallback
• Mutations are wrapped in fromPromise and provided via .provide()
• Query cache updates happen in mutation callbacks, not machine actions
• Cleanup functions are returned from callback actors
• QueryClient is passed through machine input/context

Always

• Run type checks (pnpm run typecheck)
• Run tests (pnpm run test)

---

Detailed Reference Documentation

For comprehensive patterns, examples, and in-depth guidance, consult these reference files:

• references/machine-patterns.md - Complete XState machine patterns including hierarchical states, parallel states, actors, testing, and migration from v4
• references/store-patterns.md - Full @xstate/store patterns including selectors, atoms, effects, undo/redo, and when to migrate to machines
• references/query-patterns.md - Complete TanStack Query integration patterns with QueryObserver, mutations, and full machine examples