eslint-plugin-xstate

3.2.1 verified Sat Apr 25 auth: no javascript

ESLint plugin providing lint rules for XState state machine definitions. Current stable version is 3.2.1 (Dec 2023). Actively maintained, regular releases. Key differentiators: supports both XState v4 and v5 via configuration; includes shareable recommended and all rule sets; catches common mistakes like infinite loops, invalid state/transition props, misplaced onDone, and more. Requires ESLint ^8.40.0.

Common errors

error Error: Failed to load plugin 'xstate' declared in '.eslintrc.json': Cannot find module 'eslint-plugin-xstate' ↓

cause Missing installation of eslint-plugin-xstate.

fix

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

error Error: Failed to load config "plugin:xstate/recommended" to extend from. ↓

cause eslint-plugin-xstate not installed or version too old.

fix

npm install eslint-plugin-xstate@latest --save-dev

error Definition for rule 'xstate/spawn-usage' was not found. ↓

cause Plugin not registered in plugins section or rule name misspelled.

fix

Add "plugins": ["xstate"] to your ESLint config.

error ESLint couldn't find the plugin "eslint-plugin-xstate". This is most likely an issue with the plugin resolution. ↓

cause Plugin installed but not declared in package.json dependencies while using local ESLint.

fix

Ensure eslint-plugin-xstate is in devDependencies and installed.

Warnings

breaking Version 3.0.0 requires ESLint >= 8.40.0. Older ESLint versions will cause errors. ↓

fix Update ESLint to >=8.40.0: npm install eslint@^8.40.0 --save-dev

breaking Version 3.0.0 drops support for shareable configurations without version suffix. Now default is XState v5; use 'recommended_v4' for v4. ↓

fix If using XState v4, change extends to 'plugin:xstate/recommended_v4' or set version in settings.

breaking Version 2.0.0 added support for XState v5 but may break existing rules due to new v5 syntax. ↓

fix Review XState v5 migration; use 'recommended_v4' config or set version:4 in settings.

gotcha Shareable configurations default to XState v5. If you use XState v4 without specifying, you may get false positives. ↓

fix Set "settings": { "xstate": { "version": 4 } } or use 'recommended_v4' config.

gotcha Rule 'spawn-usage' is only applicable for XState v4; using it with v5 may report errors incorrectly. ↓

fix Disable spawn-usage if using XState v5, or use version-specific config.

gotcha Rule 'no-auto-forward' reports error if autoForward is found in XState v5, as it is deprecated in v5. ↓

fix Remove autoForward from XState v5 definitions.

Install

npm install eslint-plugin-xstate

yarn add eslint-plugin-xstate

pnpm add eslint-plugin-xstate

Imports

plugin
wrong
```
// Wrong: { "plugins": ["eslint-plugin-xstate"] }
```
correct
```
// In .eslintrc: { "plugins": ["xstate"] }
```
ESLint plugin registration in config file; prefix 'eslint-plugin-' is omitted.

recommended config

wrong

// Wrong: { "extends": "plugin:xstate/recommended" } (must be array)

correct

// In .eslintrc: { "extends": ["plugin:xstate/recommended"] }

Uses plugin:xstate/recommended; for XState v4 use plugin:xstate/recommended_v4.

rules

wrong

// Wrong: { "rules": { "spawn-usage": "error" } }

correct

// In .eslintrc: { "rules": { "xstate/spawn-usage": "error" } }

All rule names must be prefixed with 'xstate/'.

Quickstart

ESLint config to enable xstate plugin, use recommended rules (XState v5), and customize event/state naming conventions.

// .eslintrc.json
{
  "plugins": ["xstate"],
  "extends": ["plugin:xstate/recommended"],
  "rules": {
    "xstate/event-names": ["warn", "camelCase"],
    "xstate/state-names": ["warn", "camelCase"]
  },
  "settings": {
    "xstate": {
      "version": 5
    }
  }
}

// Install:
// npm install eslint-plugin-xstate --save-dev
// npm install eslint --save-dev