Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mattpocock/xstate-codegen
A codegen tool for 100% TS type-safety in XState
https://github.com/mattpocock/xstate-codegen
cli codegen state-machines typescript xstate
Last synced: 9 days ago
JSON representation
A codegen tool for 100% TS type-safety in XState
- Host: GitHub
- URL: https://github.com/mattpocock/xstate-codegen
- Owner: mattpocock
- License: mit
- Archived: true
- Created: 2020-07-30T14:26:54.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-03-05T08:46:02.000Z (over 1 year ago)
- Last Synced: 2024-10-02T12:08:04.655Z (about 1 month ago)
- Topics: cli, codegen, state-machines, typescript, xstate
- Language: TypeScript
- Homepage:
- Size: 1.56 MB
- Stars: 245
- Watchers: 10
- Forks: 12
- Open Issues: 38
-
Metadata Files:
- Readme: readme.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome_xstate - XState Codegen - generate 100% typesafe Typescript code with a CLI (Awesome XState / Tools)
- awesome-list - xstate-codegen - safety in XState | mattpocock | 212 | (TypeScript)
README
> 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](https://stately.ai/blog/introducing-typescript-typegen-for-xstate) 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!](https://codesandbox.io/s/xstate-codegen-example-7etw2?file=/src/demo.machine.ts)
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`:
```ts
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:
```ts
import { Machine } from '@xstate/compiled';
interface Context {}
type Event = { type: 'DUMMY_TYPE' };
const machine = Machine({});
```
### Usage with React
```ts
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
```ts
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`.