ESLint Plugin

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 12.0.0 or later, and npm 6.9.0 or later. 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-jsx-a11y, eslint-plugin-react, and eslint-plugin-prettier projects. It also includes an optional integration with @typescript-eslint/eslint-plugin that gets activated when the typescript package is installed in the project.

There is also recommended-with-formatting ruleset for projects that want to opt out from Prettier. It 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
• es5
• esnext
• jsdoc
• jsx-a11y
• react
• i18n
• test-e2e
• test-unit

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	✓
gutenberg-phase	Governs the use of the process.env.GUTENBERG_PHASE constant	✓
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-unused-vars-before-return	Disallow assigning variable values if unused before a return	✓
react-no-unsafe-timeout	Disallow unsafe setTimeout in component
valid-sprintf	Enforce valid sprintf usage	✓
i18n-ellipsis	Disallow using three dots in translatable strings	✓
i18n-no-collapsible-whitespace	Disallow collapsible 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	✓

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

---

This fork contains a few cleanups and one style change by not requiring and remooving spaces around parentheses.