/eslint-plugin-xstate

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

Primary LanguageJavaScriptMIT LicenseMIT

eslint-plugin-xstate

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

npm version build status code style: prettier PRs Welcome

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/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"]
}

Supported Rules

Possible Errors

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

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 ✔️
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