Stately and XState

https://stately.ai/docs
Admin
Stately is a visual software modeling platform for designing state machines and actors, while XState...
Tokens:345,627
Snippets:2,972
Trust Score:9.2
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Quick start from source

Source: https://stately.ai/docs/self-hosting

Install dependencies, build the app, and start the default no-auth deployment. The editor listens on http://localhost:3000.

```bash
pnpm install
AUTH_PROVIDER=none EDITOR_SYNC_AUTH_REQUIRED=false AI_ENABLED=false pnpm build:app
AUTH_PROVIDER=none EDITOR_SYNC_AUTH_REQUIRED=false AI_ENABLED=false pnpm start -H 0.0.0.0
```

--------------------------------

### Quick start with createStore and events

Source: https://stately.ai/docs/xstate-store

Quick start example showing how to create a store with a schema, handle events, subscribe to snapshots, listen to emitted events, and trigger an event. The example logs the updated context and the emitted event.

```typescript
import { createStore } from '@xstate/store';
import { z } from 'zod';

const store = createStore({
  schemas: {
    emitted: {
      increased: z.object({ by: z.number(), total: z.number() }),
    },
  },
  context: { count: 0 },
  on: {
    inc: (context, event: { by: number }, enqueue) => {
      const count = context.count + event.by;

      enqueue.emit.increased({ by: event.by, total: count });

      return { count };
    },
  },
});

store.subscribe((snapshot) => {
  console.log(snapshot.context);
});

store.on('increased', (event) => {
  console.log(`Count increased by ${event.by}`);
});

store.trigger.inc({ by: 2 });
// logs { count: 2 }
// logs "Count increased by 2"
```

--------------------------------

### Install XState with npm

Source: https://stately.ai/docs

Install the XState library using npm. This is the first step in the quick start guide.

```bash
npm install xstate
```

--------------------------------

### Quick start with createStore and injectStore

Source: https://stately.ai/docs/xstate-store/angular

Quick start example showing how to create a store and use injectStore to subscribe to a selected value as an Angular signal.

```typescript
import { Component } from '@angular/core';
import { createStore, injectStore } from '@xstate/store-angular'; 

const store = createStore({
  context: { count: 0 },
  on: {
    inc: (context, event: { by?: number }) => ({
      count: context.count + (event.by ?? 1),
    }),
  },
});

@Component({
  selector: 'app-counter',
  standalone: true,
  template: `
    <div>
      <p>Count: {{ count() }}</p>
      <button (click)="store.trigger.inc()">+1</button>
      <button (click)="store.trigger.inc({ by: 5 })">+5</button>
    </div>
  `,
})
export class CounterComponent {
  store = store;
  count = injectStore(store, (state) => state.context.count);
}
```

--------------------------------

### Quick start with createStore and useSelector

Source: https://stately.ai/docs/xstate-store/preact

Quick start example showing how to create a store with createStore and subscribe to its state with useSelector in a Preact component.

```tsx
import { createStore, useSelector } from '@xstate/store-preact'; 

const store = createStore({
  context: { count: 0 },
  on: {
    inc: (context, event: { by?: number }) => ({
      count: context.count + (event.by ?? 1),
    }),
  },
});

function Counter() {
  const count = useSelector(store, (state) => state.context.count);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => store.trigger.inc()}>+1</button>
      <button onClick={() => store.trigger.inc({ by: 5 })}>+5</button>
    </div>
  );
}
```

--------------------------------

### Cheatsheet: setup a machine with implementations

Source: https://stately.ai/docs/machines.mdx

Use setup() to define actions, guards, actors, and delays with implementations, then call createMachine() to create the machine. The example shows a machine with a delay of 1000ms.

```TypeScript
import { setup } from 'xstate';

const machine = setup({
  actions: {
    someAction: () => {
      /* ... */
    },
  },
  guards: {
    someGuard: ({ context }) => context.count <= 10,
  },
  actors: {
    someActor: fromPromise(async () => {
      /* ... */
    }),
  },
  delays: {
    someDelay: () => 1000,
  },
}).createMachine({
  // ... Rest of machine config
});
```

--------------------------------

### Compute state transitions with initialTransition and transition

Source: https://stately.ai/docs/pure-transitions

Use initialTransition and transition from XState to compute state transitions without side effects. The example creates a machine with a pending and started state, then shows how to get the initial state and actions, and how to send a 'start' event to get the next state and actions. This is useful for server-side applications, testing, and scenarios where you need to compute state transitions without side effects.

```javascript
import { createMachine, initialTransition, transition } from 'xstate';

const machine = createMachine({
  initial: 'pending',
  states: {
    pending: {
      on: {
        start: { target: 'started' },
      },
    },
    started: {
      entry: { type: 'doSomething' },
    },
  },
});

// Get initial state and actions
const [initialState, initialActions] = initialTransition(machine);

console.log(initialState.value); // 'pending'
console.log(initialActions); // [{ type: 'doSomething', ... }]

// Get next state and actions
const [nextState, actions] = transition(machine, initialState, {
  type: 'start', // The event to send
});

console.log(nextState.value); // 'started'
console.log(actions); // [{ type: 'doSomething', ... }]
```

--------------------------------

### Strongly typing context and events with setup

Source: https://stately.ai/docs/xstate-store

Use `setup(…)` to strongly type the `context` and `events` for the state machine. The `createMachine` call is the same as the previous example.

```typescript
import { setup } from 'xstate';

const machine = setup({
  types: {
    context: {} as { count: number; name: string },
    events: {} as { type: 'inc'; by: number },
  },
}).createMachine({
  // Same as the previous example
});
```

--------------------------------

### Provide default implementations with setup

Source: https://stately.ai/docs/machines.mdx

Provides default implementations (actions, actors, guards, delays) in a setup({...}) function when creating a machine. The action is referenced by a JSON-serializable string in the machine config and logs 'Doing something!' when the actor starts.

```ts
import { setup } from 'xstate';

const feedbackMachine = setup({
  // Default implementations
  actions: {
    doSomething: () => {
      console.log('Doing something!');
    },
  },
  actors: {
    /* ... */
  },
  guards: {
    /* ... */
  },
  delays: {
    /* ... */
  },
}).createMachine({
  entry: { type: 'doSomething' },
  // ... rest of machine config
});

const feedbackActor = createActor(feedbackMachine);

feedbackActor.start();
// logs 'Doing something!'
```

--------------------------------

### Define actions with setup and use in transitions, entry, and exit

Source: https://stately.ai/docs/actions

Shows how to define actions in the setup function and reference them in transition, entry, and exit arrays. The example tracks a response on a 'feedback.good' event, shows confetti on entering the 'thanks' state, and fires an exit action when leaving the 'question' state.

```TypeScript
import { setup } from 'xstate';

function trackResponse(response: string) {
  // ...
}

const feedbackMachine = setup({
  actions: {
    track: (_, params: { response: string }) => {
      trackResponse(params.response);
      // Tracks { response: 'good' }
    },
    showConfetti: () => {
      // ...
    }
  }
}).createMachine({
  // ...
  states: {
    // ...
    question: {
      on: {
        'feedback.good': {
          actions: [
            { type: 'track', params: { response: 'good' } }
          ]
        }
      },
      exit: [
        { type: 'exitAction' }
      ]
    }
    thanks: {
      entry: [
        { type: 'showConfetti' }
      ],
    }
  }
});
```

--------------------------------

### Typed machine with setup() and .types

Source: https://stately.ai/docs/machines.mdx

Use setup() with a types object to strongly type context, events, actions, guards, and actors. Requires TypeScript 5.0+. The example shows a feedback machine with typed context, events, and an invoked actor whose output is typed as number.

```TypeScript
import { setup, fromPromise } from 'xstate';

const someAction = () => {
  /* ... */
};

const someGuard = ({ context }) => context.count <= 10;

const someActor = fromPromise(async () => {
  // ...
  return 42;
});

const feedbackMachine = setup({
  types: {
    context: {} as { count: number },
    events: {} as { type: 'increment' } | { type: 'decrement' },
  },
  actions: {
    someAction,
  },
  guards: {
    someGuard,
  },
  actors: {
    someActor,
  },
}).createMachine({
  initial: 'counting',
  states: {
    counting: {
      entry: { type: 'someAction' }, // strongly-typed
      invoke: {
        src: 'someActor', // strongly-typed
        onDone: {
          actions: ({ event }) => {
            event.output; // strongly-typed as number
          },
        },
      },
      on: {
        increment: {
          guard: { type: 'someGuard' }, // strongly-typed
          actions: assign({
            count: ({ context }) => context.count + 1,
          }),
        },
      },
    },
  },
});
```

--------------------------------

### Cheatsheet: type-bound action helpers

Source: https://stately.ai/docs/machines.mdx

Use setup() with types to create type-bound action helpers like createAction, assign, raise, emit, and log. The example shows a machine with typed context and events, and uses these helpers in entry and on handlers.

```TypeScript
import { setup } from 'xstate';

const machineSetup = setup({
  types: {
    context: {} as { count: number },
    events: {} as { type: 'increment' } | { type: 'reset' },
    emitted: {} as { type: 'COUNT_CHANGED' },
  },
});

// Custom action
const customAction = machineSetup.createAction(({ context, event }) => {
  console.log(context.count, event.type);
});

// Type-bound built-ins
const increment = machineSetup.assign({
  count: ({ context }) => context.count + 1,
});
const raiseReset = machineSetup.raise({ type: 'reset' });
const emitEvent = machineSetup.emit({ type: 'COUNT_CHANGED' });
const logCount = machineSetup.log(({ context }) => `Count: ${context.count}`);

const machine = machineSetup.createMachine({
  context: { count: 0 },
  entry: [customAction, increment, emitEvent],
  on: {
    increment: { actions: increment },
    reset: { actions: raiseReset },
  },
});
```

--------------------------------

### Type-safe finite states with setup() and createActor

Source: https://stately.ai/docs/finite-states

Use `setup(...).createMachine(...)` to define a machine with strongly typed context and events. This example shows a feedback machine with typed events and demonstrates type-safe state matching and value access.

```typescript
import { setup, createActor } from 'xstate';

const feedbackMachine = setup({
  types: {
    context: {} as { feedback: string; rating: number },
    events: {} as
      | { type: 'feedback.good' }
      | { type: 'feedback.bad' }
      | { type: 'feedback.submit' },
  },
}).createMachine({
  id: 'feedback',
  initial: 'prompt',
  context: {
    feedback: '',
    rating: 0,
  },
  states: {
    prompt: {
      on: {
        'feedback.good': { target: 'thanks' },
        'feedback.bad': { target: 'form' },
      },
    },
    form: {
      on: {
        'feedback.submit': { target: 'thanks' },
      },
    },
    thanks: {
      type: 'final',
    },
  },
});

const feedbackActor = createActor(feedbackMachine).start();

// ✅ Type-safe and autocompletes
const currentState = feedbackActor.getSnapshot();

// ✅ `state.matches(...)` is type-safe with autocompletion
if (currentState.matches('prompt')) {
  // TypeScript knows we're in the 'prompt' state
}

// ✅ All state values have autocompletion
const isFormState = currentState.matches('form');
const isThanksState = currentState.matches('thanks');

// ✅ `state.value` is also strongly typed
const stateValue = currentState.value; // 'prompt' | 'form' | 'thanks'
```

--------------------------------

### Cheatsheet: extend setup implementations

Source: https://stately.ai/docs/machines.mdx

Extend a base setup with additional guards, actions, and delays using .extend(). The example uses not() and and() to compose guards, and overrides a delay with a number.

```TypeScript
import { and, not, setup } from 'xstate';

const baseSetup = setup({
  guards: {
    isAuthenticated: () => true,
    hasPermission: () => false,
  },
});

const appSetup = baseSetup.extend({
  guards: {
    isUnauthenticated: not('isAuthenticated'),
    canAccess: and(['isAuthenticated', 'hasPermission']),
  },
  actions: {
    trackAccess: () => {
      /* ... */
    },
  },
  delays: {
    shortDelay: 250,
  },
});

const machine = appSetup.createMachine({
  // ... Rest of machine config
});
```

--------------------------------

### Use initialTransition and transition to compute next state and actions

Source: https://stately.ai/docs/machines.mdx

Imports `createMachine`, `initialTransition`, and `transition` from 'xstate'. Defines a machine with 'pending' and 'started' states, then uses `initialTransition` to get the initial state and actions, and `transition` to compute the next state and actions when a 'start' event is sent. Logs the results to the console.

```ts
import { createMachine, initialTransition, transition } from 'xstate';

const machine = createMachine({
  initial: 'pending',
  states: {
    pending: {
      on: {
        start: { target: 'started' },
      },
    },
    started: {
      entry: 'doSomething',
    },
  },
});

const [initialState, initialActions] = initialTransition(machine);

console.log(initialState.value);
// logs 'pending'

console.log(initialActions);
// logs []

const [nextState, actions] = transition(machine, initialState, {
  type: 'start',
});

console.log(nextState.value);
// logs 'started'

console.log(actions);
// logs [{ type: 'doSomething', â€¦ }]
```

--------------------------------

### Migrate from createMachine to setup()

Source: https://stately.ai/docs/setup

Migrate from bare `createMachine({ ... })` to `setup({ ... }).createMachine({ ... })`. Move types and sources from the second argument of `createMachine` into `setup`.

```typescript
import {
// createMachine
  setup
} from 'xstate';

const machine =
  setup({
    types: { ... },
    actions: { ... },
    guards: { ... }
  })
  .createMachine({
    // types: { ... }
  }, /* { actions, guards, ... } */);
```

--------------------------------

### Install @xstate/store-preact

Source: https://stately.ai/docs/xstate-store/preact

Install the @xstate/store-preact package, which re-exports all of @xstate/store.

```bash
npm install @xstate/store-preact
```

--------------------------------

### Install @xstate/store-svelte

Source: https://stately.ai/docs/xstate-store/svelte

Install the @xstate/store-svelte package, which re-exports @xstate/store.

```bash
npm install @xstate/store-svelte
```

--------------------------------

### Cheatsheet: input

Source: https://stately.ai/docs/context

Pass input to a machine using the input option in createActor. The example defines a setup with typed context and input, uses the input to initialize the context's rating, and starts the actor with the provided input.

```typescript
import { setup, createActor } from 'xstate';

const feedbackMachine = setup({
  types: {
    context: {} as {
      feedback: string;
      rating: number;
    },
    input: {} as {
      defaultRating: number;
    },
  },
}).createMachine({
  context: ({ input }) => ({
    feedback: '',
    rating: input.defaultRating,
  }),
});

const feedbackActor = createActor(feedbackMachine, {
  input: {
    defaultRating: 5,
  },
}).start();
```

--------------------------------

### Setting up actions

Source: https://stately.ai/docs/actions

Shows how to define an action in setup() and reference it in the machine's entry actions.

```javascript
import { setup } from 'xstate';

const someAction = () => {
  //...
};

const machine = setup({
  actions: {
    someAction,
  },
}).createMachine({
  entry: [
    { type: 'someAction' },
  ],
  // ...
});
```

--------------------------------

### Get next transitions with getNextTransitions

Source: https://stately.ai/docs/machines.mdx

Use getNextTransitions(state) to retrieve all potential next transitions from a given state. The example creates a machine with idle, running, and paused states, starts an actor, and logs the event types of the transitions from the initial state, which outputs ['start', 'reset']. The function returns an array of transition definitions with properties eventType, target, source, actions, reenter, and guard.

```ts
import { createMachine, createActor, getNextTransitions } from 'xstate';

const machine = createMachine({
  initial: 'idle',
  states: {
    idle: {
      on: {
        start: { target: 'running' },
        reset: { target: 'idle' },
      },
    },
    running: {
      on: {
        stop: { target: 'idle' },
        pause: { target: 'paused' },
      },
    },
    paused: {
      on: {
        resume: { target: 'running' },
        stop: { target: 'idle' },
      },
    },
  },
});

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

const transitions = getNextTransitions(actor.getSnapshot());

console.log(transitions.map((t) => t.eventType));
// logs ['start', 'reset']
```

--------------------------------

### Setup types and actions with setup()

Source: https://stately.ai/docs/setup

Use `setup({ ... })` to define types and sources for a machine, reducing boilerplate and improving type inference. Requires TypeScript 5.0 or higher.

```typescript
import { setup, assign } from 'xstate';

const machine = setup({
  types: {
    context: {} as { count: number },
    events: {} as { type: 'inc' } | { type: 'dec' },
  },
  actions: {
    increment: assign({
      count: ({ context }) => context.count + 1,
    }),
    decrement: assign({
      count: ({ context }) => context.count - 1,
    }),
  },
}).createMachine({
  context: { count: 0 },
  on: {
    inc: { actions: 'increment' },
    dec: { actions: 'decrement' },
  },
});
```

--------------------------------

### Complete self-hosted setup commands

Source: https://stately.ai/docs/packages/cli

Complete setup for a self-hosted deployment: login, init with --scan, and open with a custom editor URL. The --base-url is used by init, status, diff, push, and pull; --editor-url is used only by open and defaults to https://editor.stately.ai.

```bash
statelyai login --base-url https://editor.example.com/api/mcp
statelyai init --base-url https://studio.example.com --scan
statelyai open src/checkout.machine.ts \
  --editor-url https://editor.example.com
```

--------------------------------

### Use actor.getSnapshot() to get actor's state

Source: https://stately.ai/docs/migration

Read the current state with `actor.getSnapshot()` after starting. Subscribing after start does not emit the current snapshot immediately.

```typescript
// ✅
const actor = createActor(machine);
actor.start();

const initialState = actor.getSnapshot();

actor.subscribe((state) => {
  // Snapshots from when the subscription was created
  // Will not emit the current snapshot until a transition happens
});
```

--------------------------------

### Dynamic parameter in action with setup()

Source: https://stately.ai/docs/typescript

Defines a machine using setup() with a typed 'greet' action that receives a dynamic parameter. Used in the entry action, passing the context's user name as params.

```TypeScript
import { setup } from 'xstate';

const feedbackMachine = setup({
  types: {
    context: {} as {
      user: { name: string };
    },
  },
  actions: {
    greet: (_, params: { name: string }) => {
      console.log(`Hello, ${params.name}!`);
    },
  },
}).createMachine({
  context: {
    user: {
      name: 'David',
    },
  },
  // ...
  entry: {
    type: 'greet',
    params: ({ context }) => ({
      name: context.user.name,
    }),
  },
});
```

--------------------------------

### Typed output with setup and OutputFrom

Source: https://stately.ai/docs/output

Demonstrates typing the output property in the machine setup and using it in the output function. Requires TypeScript 5.0 or greater.

```typescript
import { setup, createActor } from 'xstate';

const machine = setup({
  types: {
    output: {} as { total: number },
  },
}).createMachine({
  // ...
  output: ({ context }) => ({
    total: context.items.reduce((total, item) => total + item.price, 0),
  }),
});

const actor = createActor(machine);

actor.subscribe((snapshot) => {
  if (snapshot.status === 'done') {
    console.log(snapshot.output.total);
  }
});
```

--------------------------------

### fromState option

Source: https://stately.ai/docs/graph

Start traversal from a specific state instead of the initial state. The example creates an actor, sends an event, and uses the resulting snapshot as the starting state.

```typescript
import { createActor } from 'xstate';

const actor = createActor(feedbackMachine).start();
actor.send({ type: 'CLICK_BAD' });

const paths = getShortestPaths(feedbackMachine, {
  fromState: actor.getSnapshot()
});

// Paths starting from 'form' state
```

--------------------------------

### Invoking Observables

Source: https://stately.ai/docs/invoke.mdx

Documentation for invoking observable actors in XState, including setup and invocation example.

```APIDOC
## Invoking Observables

### Description
Invoke observable actor logic by setting it up in the `actors` object of `setup()` and referencing it by its source name in the `invoke` property of a state.

### Method
N/A (State machine invocation)

### Endpoint
N/A

### Parameters
#### `invoke` object
- **src** (string) - Required - The source name of the observable actor logic.
- **input** (object) - Optional - Input data passed to the observable actor logic.
- **onSnapshot** (object) - Optional - Action to execute when the observable emits a snapshot.

### Request Example
```ts
import { setup, fromObservable } from 'xstate';
import { interval } from 'rxjs';

const machine = setup({
  actors: {
    someObservable: fromObservable(({ input }: { input: number }) => {
      return interval(input.ms);
    }),
  },
}).createMachine({
  // ...
  invoke: {
    src: 'someObservable',
    input: { ms: 1000 },
    onSnapshot: {
      actions: ({ event }) => {
        console.log(event.snapshot.context); // 1, 2, 3, ...
      },
    },
  },
});
```

### Response
N/A
```

--------------------------------

### Invoking Callbacks

Source: https://stately.ai/docs/invoke.mdx

Documentation for invoking callback actors in XState, including setup and invocation example.

```APIDOC
## Invoking Callbacks

### Description
Invoke callback actor logic by setting it up in the `actors` object of `setup()` and referencing it by its source name in the `invoke` property of a state.

### Method
N/A (State machine invocation)

### Endpoint
N/A

### Parameters
#### `invoke` object
- **src** (string) - Required - The source name of the callback actor logic.
- **input** (object) - Optional - Input data passed to the callback actor logic.

### Request Example
```ts
import { setup, fromCallback } from 'xstate';

const machine = setup({
  actors: {
    someCallback: fromCallback(({ input, sendBack, receive }) => {
      // ...
    }),
  },
}).createMachine({
  // ...
  invoke: {
    src: 'someCallback',
    input: {
      /* ... */
    },
  },
});
```

### Response
N/A
```

--------------------------------

### Development commands for install, verify, and benchmarks

Source: https://stately.ai/docs/packages/graph

Development commands for installing dependencies, verifying the build, and running benchmarks. The bench commands include micro-benchmarks, cross-library comparisons, a quick comparison, and report rendering.

```bash
pnpm install
pnpm verify
pnpm bench                # micro-benchmarks (vitest bench)
pnpm bench:compare        # cross-library comparison run
pnpm bench:compare:quick  # faster, smaller-sample comparison
pnpm bench:report         # render the comparison results
```

--------------------------------

### Declare @agent.usage event in a plain setup() machine

Source: https://stately.ai/docs/packages/agent/usage-and-budgets

A setupAgent machine already declares '@agent.usage' in its event union, but a machine built with plain setup() must declare it manually. This example shows the required schema and handler.

```javascript
import { z } from "zod";
import { createActor, setup } from "xstate";

const machine = setup({
  schemas: {
    context: z.object({ tokens: z.number() }),
    events: {
      // The reserved type, declared by hand.
      "@agent.usage": z.object({ usage: z.object({ totalTokens: z.number().optional() }) }),
      GO: z.object({}),
    },
  },
}).createMachine({
  context: { tokens: 0 },
  on: {
    "@agent.usage": ({ context, event }) => ({
      context: { tokens: context.tokens + (event.usage.totalTokens ?? 0) },
    }),
  },
  // …states
});
```

--------------------------------

### Clone and run benchmarks

Source: https://stately.ai/docs/packages/graph/benchmarks

Clones the repository, installs dependencies, and runs the benchmark. The quick variant covers 1k and 10k sizes, while the full variant adds 100k and is the canonical set.

```bash
git clone https://github.com/statelyai/graph.git
cd graph
pnpm install            # installs @statelyai/graph's toolchain + every competitor lib

pnpm bench:compare:quick   # 1k + 10k sizes — finishes in a couple of minutes
pnpm bench:compare         # full 1k + 10k + 100k — several minutes, canonical sizes
```

--------------------------------

### useActorRef basic example

Source: https://stately.ai/docs/xstate-vue

Basic usage of `useActorRef` to create an actor ref from a machine and return it from the component's setup function.

```javascript
import { useActorRef } from '@xstate/vue';
import { someMachine } from '../path/to/someMachine';

export default {
  setup() {
    const actorRef = useActorRef(someMachine);
    return actorRef;
  },
};
```

--------------------------------

### Define and pass input to a machine with setup() and createActor()

Source: https://stately.ai/docs/input.mdx

Shows how to define input types in setup() and use them in the context initializer, then pass input when creating the actor with createActor(). The input type must be declared in the types.input property; the context function receives input as its argument.

```ts
import { createActor, setup } from 'xstate';

const feedbackMachine = setup({
  types: {
    context: {} as {
      userId: string;
      feedback: string;
      rating: number;
    },
    // [!code highlight:4]
    input: {} as {
      userId: string;
      defaultRating: number;
    },
  },
}).createMachine({
  // [!code highlight:1]
  context: ({ input }) => ({
    // [!code highlight:1]
    userId: input.userId,
    feedback: '',
    // [!code highlight:1]
    rating: input.defaultRating,
  }),
  // ...
});

const feedbackActor = createActor(feedbackMachine, {
  // [!code highlight:4]
  input: {
    userId: '123',
    defaultRating: 5,
  },
});
```

--------------------------------

### Invoke actors with TypeScript inference using setup API

Source: https://stately.ai/docs/invoke.mdx

Use the setup API to properly infer types for invoked actor logic. Requires TypeScript 5.0 or greater. The example shows a fetchUser actor with typed input and output, and an invoke with input and onDone actions.

```TypeScript
import { setup, fromPromise, assign } from 'xstate';

interface User {
  id: string;
  name: string;
}

const machine = setup({
  actors: {
    // [!code highlight:5]
    fetchUser: fromPromise<User, { userId: string }>(async ({ input }) => {
      const response = await fetch(`https://example.com/${input.userId}`);

      return response.json();
    }),
  },
}).createMachine({
  // ...
  context: {
    user: null,
    userId: 42,
  },
  initial: 'idle',
  states: {
    idle: {
      on: {
        editUserDetails: { target: 'loadingUser' },
      },
    },
    loadingUser: {
      invoke: {
        // [!code highlight:9]
        src: 'fetchUser',
        input: ({ context }) => ({
          userId: context.userId, // Type enforced to be string
        }),
        onDone: {
          actions: assign({
            user: ({ event }) => event.output, // Strongly typed as User
          }),
        },
      },
    },
  },
});
```

--------------------------------

### Install xstate and @xstate/test

Source: https://stately.ai/docs/xstate-test

Install the xstate and @xstate/test packages using npm.

```bash
npm install xstate @xstate/test
```

--------------------------------

### Cheatsheet: create a machine

Source: https://stately.ai/docs/machines.mdx

Minimal example of creating a machine with createMachine(), specifying an initial state and a states object. Use as a starting point for any XState machine.

```TypeScript
import { createMachine } from 'xstate';

const machine = createMachine({
  initial: 'start',
  states: {
    start: {},
    // ...
  },
});
```

--------------------------------

### Install @xstate/store with npm

Source: https://stately.ai/docs/xstate-store

Install the @xstate/store package using npm.

```bash
npm install @xstate/store
```

--------------------------------

### TypeScript delays with setup()

Source: https://stately.ai/docs/delayed-transitions

Shows how to strongly type delays by defining them in the setup() function, with a machine using the 'shortTimeout' delay.

```typescript
import { setup } from 'xstate';

const machine = setup({
  delays: {
    shortTimeout: 1000,
    longTimeout: 5000,
    eventually: 10_000,
  },
}).createMachine({
  after: {
    shortTimeout: {
      /* ... */
    },
  },
});
```

--------------------------------

### Define initial state with 'initial' property

Source: https://stately.ai/docs/finite-states

Use the 'initial' property on the machine config to set the starting state. The example defines a 'feedbackMachine' with 'initial: 'prompt'' and a 'prompt' state node.

```javascript
import { createMachine } from 'xstate';

const feedbackMachine = createMachine({
  id: 'feedback',

  // Initial state
  initial: 'prompt',

  // Finite states
  states: {
    prompt: {
      /* ... */
    },
    // ...
  },
});
```

--------------------------------

### Strongly Typed Actions with types.actions in XState

Source: https://stately.ai/docs/actions

Without setup, strongly type the machine's actions using the types.actions property. The example defines a union of action types with their params, then uses them in entry actions.

```typescript
import { createMachine } from 'xstate';

const machine = createMachine({
  types: {} as {
    actions:
      | {
          type: 'track';
          params: {
            response: string;
          };
        }
      | { type: 'increment'; params: { value: number } };
  },
  // ...
  entry: [
    { type: 'track', params: { response: 'good' } },
    { type: 'increment', params: { value: 1 } },
  ],
});
```

--------------------------------

### Strongly Typed Actions with setup() in XState v5

Source: https://stately.ai/docs/actions

Use the setup function to strongly type action implementations. The action type is the key and the implementation is the value; parameters are strongly typed as the second argument. Entry actions are then referenced with matching types and params.

```typescript
import { setup } from 'xstate';

const machine = setup({
  actions: {
    track: (_, params: { response: string }) => {
      // ...
    },
    increment: (_, params: { value: number }) => {
      // ...
    },
  },
}).createMachine({
  // ...
  entry: [
    { type: 'track', params: { response: 'good' } },
    { type: 'increment', params: { value: 1 } },
  ],
});
```

--------------------------------

### Spawning Different Actor Types

Source: https://stately.ai/docs/spawn

Shows how to spawn different actor types: a promise actor, an observable actor, and a named actor defined in setup. The named actor example passes input data to the spawned actor.

```typescript
spawnChild(
  fromPromise(() => Promise.resolve(42)),
  {
    id: 'promiseActor',
  },
);
```

```typescript
spawnChild(
  fromObservable(() => interval(1000)),
  {
    id: 'observableActor',
  },
);
```

```typescript
setup({
  actors: {
    fetchData: fromPromise(({ input }) => Promise.resolve(input)),
  },
}).createMachine({
  entry: spawnChild('fetchData', {
    id: 'fetchActor',
    input: 42,
  }),
});
```

--------------------------------

### Extend setup with setup.extend()

Source: https://stately.ai/docs/setup

Extend an existing setup with `setup.extend(...)` to add actions, guards, and delays. All base and extended implementations are available to machines created from the extended setup. Available since XState version 5.24.0.

```typescript
import { and, not, setup } from 'xstate';

const baseSetup = setup({
  guards: {
    isAuthenticated: () => true,
    hasPermission: () => false,
  },
});

const appSetup = baseSetup.extend({
  guards: {
    isUnauthenticated: not('isAuthenticated'),
    canAccess: and(['isAuthenticated', 'hasPermission']),
  },
  actions: {
    trackAccess: () => {
      console.log('Access checked');
    },
  },
  delays: {
    shortDelay: 250,
  },
});

const machine = appSetup.createMachine({
  initial: 'checking',
  states: {
    checking: {
      after: {
        shortDelay: {
          guard: 'canAccess',
          actions: 'trackAccess',
          target: 'allowed',
        },
      },
    },
    allowed: {},
  },
});
```

--------------------------------

### Install @statelyai/agent and dependencies

Source: https://stately.ai/docs/packages/agent/quickstart

Install the core packages: @statelyai/agent, xstate, and zod. Add 'ai' and a provider only when using the optional AI SDK adapter.

```bash
pnpm add @statelyai/agent@alpha xstate@alpha zod
```

--------------------------------

### Persist and restore actor state with getPersistedSnapshot() and snapshot option

Source: https://stately.ai/docs/persistence

Shows the full persistence workflow: get the persisted snapshot with getPersistedSnapshot(), store it in localStorage, then restore it by passing the snapshot to createActor() with the snapshot option and calling start().

```javascript
const feedbackActor = createActor(feedbackMachine).start();

// Get state to be persisted
const persistedState = feedbackActor.getPersistedSnapshot();

// Persist state
localStorage.setItem('feedback', JSON.stringify(persistedState));

// Restore state
const restoredState = JSON.parse(localStorage.getItem('feedback'));

const restoredFeedbackActor = createActor(feedbackMachine, {
  snapshot: restoredState,
}).start();
```

--------------------------------

### Quick start with createStore and useSelector

Source: https://stately.ai/docs/xstate-store/vue

A minimal Vue setup using createStore and useSelector from @xstate/store-vue. The store has a count context and an inc transition that accepts an optional by amount. The template displays the count and triggers inc with +1 or +5.

```vue
<script setup lang="ts">
import { createStore, useSelector } from '@xstate/store-vue'; 

const store = createStore({
  context: { count: 0 },
  on: {
    inc: (context, event: { by?: number }) => ({
      count: context.count + (event.by ?? 1),
    }),
  },
});

const count = useSelector(store, (state) => state.context.count);
</script>

<template>
  <div>
    <p>Count: {{ count }}</p>
    <button @click="store.trigger.inc()">+1</button>
    <button @click="store.trigger.inc({ by: 5 })">+5</button>
  </div>
</template>
```
Tokens:
Raw