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:

typescript

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:

typescript

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:

typescript

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

typescript

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

typescript

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:

typescript

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()

typescript

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)

Use
setup()
for all machines - provides superior type inference
Use enums for event types - UPPER_SNAKE_CASE convention
Define actions outside
setup()
- use type-bound helpers like
```
setup().assign()
```
Use
enqueueActions()
for sequential actions - group related actions together
Use
.provide()
for React integration - override actions with external methods
Initialize context from
input
- use function form for dynamic initialization
Always spread
...context
in stores - preserve other properties
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

xstate

NPX Install

Tags

SKILL.md Content

XState v5 Developer Guide

Quick Reference

Core Principles

XState State Machines

@xstate/store

XState + TanStack Query Integration

XState State Machines

Creating a Machine with setup() API

React Integration

@xstate/store

Creating a Store

React Integration

Undo/Redo Pattern

XState + TanStack Query Integration

Query Subscriptions with QueryObserver

Mutations with useMutation

Essential Patterns (All Tools)

When to Use Each Tool

Use XState State Machines When:

Use @xstate/store When:

Use XState + TanStack Query When:

Common Pitfalls to Avoid

All XState Tools

@xstate/store Specific

TanStack Query Integration

Validation Checklist

For State Machines

For @xstate/store

For TanStack Query Integration

Always

Detailed Reference Documentation