ESLint plugin including configurations and custom rules for WordPress development.
Installation
Install the module
npm install @wordpress/eslint-plugin --save-dev
Note: This package requires Node.js version with long-term support status (check Active LTS or Maintenance LTS releases). It is not compatible with older versions.
Usage
To opt-in to the default configuration, extend your own project’s .eslintrc
file:
{
"extends": [ "plugin:@wordpress/eslint-plugin/recommended" ]
}
Refer to the ESLint documentation on Shareable Configs for more information.
The recommended
preset will include rules governing an ES2015+ environment, and includes rules from the eslint-plugin-jsdoc
, eslint-plugin-jsx-a11y
, eslint-plugin-react
, and other similar plugins.
This preset offers an optional integration with the eslint-plugin-prettier
package that runs Prettier code formatter and reports differences as individual ESLint issues. You can activate it by installing the prettier
package separately with:
npm install prettier --save-dev
Finally, this ruleset also includes an optional integration with the @typescript-eslint/eslint-plugin
package that enables ESLint to support TypeScript language. You can activate it by installing the typescript
package separately with:
npm install typescript --save-dev
There is also recommended-with-formatting
ruleset for projects that want to ensure that Prettier and TypeScript integration is never activated. This preset has the native ESLint code formatting rules enabled instead.
Rulesets
Alternatively, you can opt-in to only the more granular rulesets offered by the plugin. These include:
custom
– custom rules for WordPress development.es5
– rules for legacy ES5 environments.esnext
– rules for ES2015+ environments.i18n
– rules for internationalization.jsdoc
– rules for JSDoc comments.jsx-a11y
– rules for accessibility in JSX.react
– rules for React components.test-e2e
– rules for end-to-end tests written in Puppeteer.test-unit
– rules for unit tests written in Jest.test-playwright
– rules for end-to-end tests written in Playwright.
For example, if your project does not use React, you could consider extending including only the ESNext rules in your project using the following extends
definition:
{
"extends": [ "plugin:@wordpress/eslint-plugin/esnext" ]
}
These rules can be used additively, so you could extend both esnext
and custom
rulesets, but omit the react
and jsx-a11y
configurations.
The granular rulesets will not define any environment globals. As such, if they are required for your project, you will need to define them yourself.
Rules
Rule | Description | Recommended |
---|---|---|
data-no-store-string-literals | Discourage passing string literals to reference data stores. | |
dependency-group | Enforce dependencies docblocks formatting. | ✓ |
i18n-ellipsis | Disallow using three dots in translatable strings. | ✓ |
i18n-hyphenated-range | Disallow hyphenated numerical ranges in translatable strings. | |
i18n-no-collapsible-whitespace | Disallow collapsible whitespace in translatable strings. | ✓ |
i18n-no-flanking-whitespace | Disallow leading or trailing whitespace in translatable strings. | |
i18n-no-placeholders-only | Prevent using only placeholders in translatable strings. | ✓ |
i18n-no-variables | Enforce string literals as translation function arguments. | ✓ |
i18n-text-domain | Enforce passing valid text domains. | ✓ |
i18n-translator-comments | Enforce adding translator comments. | ✓ |
no-base-control-with-label-without-id | Disallow the usage of BaseControl component with a label prop set but omitting the id property. | ✓ |
no-unguarded-get-range-at | Disallow the usage of unguarded getRangeAt calls. |
✓ |
no-unsafe-wp-apis | Disallow the usage of unsafe APIs from @wordpress/* packagesl |
✓ |
no-unused-vars-before-return | Disallow assigning variable values if unused before a return. | ✓ |
no-wp-process-env | Disallow legacy usage of WordPress variables via process.env like process.env.SCRIPT_DEBUG . |
✓ |
react-no-unsafe-timeout | Disallow unsafe setTimeout in component. |
|
valid-sprintf | Enforce valid sprintf usage. | ✓ |
wp-global-usage | Enforce correct usage of WordPress globals like globalThis.SCRIPT_DEBUG . |
Legacy
If you are using WordPress’ .jshintrc
JSHint configuration and you would like to take the first step to migrate to an ESLint equivalent it is also possible to define your own project’s .eslintrc
file as:
{
"extends": [ "plugin:@wordpress/eslint-plugin/jshint" ]
}
Contributing to this package
This is an individual package that’s part of the Gutenberg project. The project is organized as a monorepo. It’s made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.
To find out more about contributing to this package or Gutenberg as a whole, please read the project’s main contributor guide.