mattpocock/xstate-codegen

XState Codegen is deprecated - we'll be bringing this exploratory work into XState core. We're convinced that typegen is the future of good typing in XState, and syncing it with core (and the XState VSCode extension) is the future.

UPDATE: We did it! Typegen is now part of XState core. See the announcement blog post to learn more. Typegen should be used in 100% of circumstances - it is an improved version of xstate-codegen.

Type Safe State Machines

xstate-codegen gives you 100% type-safe usage of XState in Typescript. Try it out at this codesandbox!

You get type safety on:

• Transition targets: on: {EVENT: 'deep.nested.state'}
• Services
• Guards
• Activities
• Actions
• The initial attribute
• state.matches('deep.nested.state')

This works by introspecting your machine in situ in your code. With this Thanos-level power, we can click our fingers and give you 100% type safety in your state machines.

Usage

CLI

xstate-codegen "src/**/**.machine.ts"

Inside code

Instead of importing createMachine or Machine from xstate, import them from @xstate/compiled:

import { createMachine } from '@xstate/compiled';

const machine = createMachine();

You must pass three type options to createMachine/Machine:

1. The desired shape of your machine's context
2. The list of events your machine accepts, typed in a discriminated union (type Event = { type: 'GO' } | { type: 'STOP' };)
3. A string ID for your machine, unique to your project.

For instance:

import { Machine } from '@xstate/compiled';

interface Context {}

type Event = { type: 'DUMMY_TYPE' };

const machine = Machine<Context, Event, 'uniqueId'>({});

Usage with React

import { useMachine } from '@xstate/compiled/react';
import { machine } from './myMachine.machine'

const [state, dispatch] = useMachine(machine, {
  // all options in here will be type checked
})

Usage with Interpret

import { interpret } from '@xstate/compiled';
import { machine } from './myMachine.machine'

const service = interpret(machine, {
  // all options in here will be type checked
})

Options

Once

xstate-codegen "src/**/**.machine.ts" --once

By default, the CLI watches for changes in your files. Running --once runs the CLI only once.

Out Dir

xstate-codegen "src/**/**.machine.ts" --outDir="src"

By default, the CLI adds the required declaration files inside node_modules at node_modules/@xstate/compiled. This writes the declaration files to a specified directory.

Note, this only writes the declaration files to the directory. The .js files still get written to node_modules/@xstate/compiled.