eslint-plugin-xstate

eslint-plugin-xstate

TODO add prefer-predictable, no-auto-forward + their docs

ESLint plugin to check for common mistakes and enforce good practices when using XState library.

Installation

You'll first need to install ESLint:

$ npm i eslint --save-dev

Next, install eslint-plugin-xstate:

$ npm install eslint-plugin-xstate --save-dev

Usage

Add xstate to the plugins section of your .eslintrc configuration file. You can omit the eslint-plugin- prefix:

{
  "plugins": ["xstate"]
}

Then configure the rules you want to use under the rules section.

{
  "rules": {
    "xstate/spawn-usage": "error",
    "xstate/no-infinite-loop": "error",
    "xstate/no-imperative-action": "error",
    "xstate/no-ondone-outside-compound-state": "error",
    "xstate/invoke-usage": "error",
    "xstate/entry-exit-action": "error",
    "xstate/prefer-always": "error",
    "xstate/prefer-predictable-action-arguments": "error",
    "xstate/no-misplaced-on-transition": "error",
    "xstate/no-invalid-transition-props": "error",
    "xstate/no-invalid-state-props": "error",
    "xstate/no-async-guard": "error",
    "xstate/event-names": ["warn", "macroCase"],
    "xstate/state-names": ["warn", "camelCase"],
    "xstate/no-inline-implementation": "warn",
    "xstate/no-auto-forward": "warn"
  }
}

Shareable Configurations

This plugin exports a recommended configuration which checks for common mistakes. To enable this configuration use the extends property in your .eslintrc.js config file:

{
  "extends": ["plugin:xstate/recommended"]
}

There is also an all configuration which includes every available rule. It enforces both correct usage and best XState practices.

{
  "extends": ["plugin:xstate/all"]
}

XState v4

The default shareable configurations are for XState v5. If you use the older XState v4, append _v4 to the name of the configuration you want to use.

{
  "extends": ["plugin:xstate/recommended_v4"]
}

{
  "extends": ["plugin:xstate/all_v4"]
}

Supported Rules

Possible Errors

Rule	Description	Recommended
spawn-usage	Enforce correct usage of spawn. Only for XState v4!	:heavy_check_mark:
no-infinite-loop	Detect infinite loops with eventless transitions	:heavy_check_mark:
no-imperative-action	Forbid using action creators imperatively	:heavy_check_mark:
no-ondone-outside-compound-state	Forbid onDone transitions on atomic, history and final nodes	:heavy_check_mark:
invoke-usage	Enforce correct invocation of services	:heavy_check_mark:
entry-exit-action	Forbid invalid declarations of entry/exit actions	:heavy_check_mark:
no-misplaced-on-transition	Forbid invalid declarations of on transitions	:heavy_check_mark:
no-invalid-transition-props	Forbid invalid properties in transition declarations	:heavy_check_mark:
no-invalid-state-props	Forbid invalid properties in state node declarations	:heavy_check_mark:
no-async-guard	Forbid asynchronous guard functions	:heavy_check_mark:

Best Practices

Rule	Description	Recommended
no-inline-implementation	Suggest refactoring guards, actions and services into machine options
prefer-always	Suggest using the always syntax for transient (eventless) transitions	:heavy_check_mark:
prefer-predictable-action-arguments	Suggest turning on the predictableActionArguments option	:heavy_check_mark:
no-auto-forward	Forbid auto-forwarding events to invoked services or spawned actors

Stylistic Issues

Rule	Description	Recommended
event-names	Suggest consistent formatting of event names
state-names	Suggest consistent formatting of state names and prevent confusing names