Registry / testing / eslint-plugin-xstate

eslint-plugin-xstate

library3.2.1jsnpmunverified

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.

testing

npm install eslint-plugin-xstate

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ESLINT-PLUGIN-XSTA

eslint-plugin-xstate

testingjavascriptv3.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

plugin

✓ // In .eslintrc: { "plugins": ["xstate"] }

✗ // Wrong: { "plugins": ["eslint-plugin-xstate"] }

ESLint plugin registration in config file; prefix 'eslint-plugin-' is omitted.

recommended config

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

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

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

rules

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

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

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

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

Debug

Known issues

breakingVersion 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

affects: >=3.0.0

breakingVersion 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.

affects: >=3.0.0

breakingVersion 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.

affects: >=2.0.0 <3.0.0

gotchaShareable 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.

affects: >=2.0.0

gotchaRule '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.

affects: >=2.0.0

gotchaRule '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.

affects: >=2.0.0

Errors

Common errors & fixes

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

Missing installation of eslint-plugin-xstate.

fix

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

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

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

fix

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

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

Plugin not registered in plugins section or rule name misspelled.

fix

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

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

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

fix

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

Upgrade

Version history

3.2.1latest on npm

Audit

Dependencies

eslintrequiredpeer dependency required for ESLint plugin functionality

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/rlaffers/eslint-plugin-xstate ↗

packagehttps://www.npmjs.com/package/eslint-plugin-xstate ↗

homepagehttps://stately.ai ↗