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.js version with long-term support status (check Active LTS or Maintenance LTS releases). It is not compatible with older versions.

Usage

Minimum ESLint version: ^9.0.0 || ^10.0.0

Upgrading from an older version? See the ESLint v10 migration guide for a comprehensive walkthrough of the breaking changes, migration steps, and troubleshooting.

Flat config (ESLint v9+, recommended)

Create an eslint.config.mjs file in your project root:

import wordpress from '@wordpress/eslint-plugin';

export default [ ...wordpress.configs.recommended ];

You can add your own overrides after the spread:

import wordpress from '@wordpress/eslint-plugin';

export default [
	...wordpress.configs.recommended,
	{
		rules: {
			// your custom rule overrides
		},
	},
];

Refer to the ESLint flat config documentation for more information.

Legacy eslintrc (ESLint v9 only, deprecated)

If you are still using ESLint v9 with the legacy .eslintrc.* format, a compatibility wrapper is available:

// .eslintrc.js
const wordpress = require( '@wordpress/eslint-plugin/eslintrc' );

module.exports = wordpress.configs.recommended;

All config presets are available through the wrapper (e.g., wordpress.configs.esnext, wordpress.configs[ 'recommended-with-formatting' ]).

Note: The eslintrc wrapper is deprecated and will be removed in the next major version. ESLint v10 does not support .eslintrc.* files at all. Please migrate to flat config.

About the recommended preset

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 use only the ESNext rules:

// eslint.config.mjs
import wordpress from '@wordpress/eslint-plugin';

export default [ ...wordpress.configs.esnext ];

These rules can be used additively, so you could spread 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-dom-globals-in-constructor | Disallow use of DOM globals in class constructors. | | | no-dom-globals-in-module-scope | Disallow use of DOM globals in module scope. | | | no-dom-globals-in-react-cc-render | Disallow use of DOM globals in React class component render methods. | | | no-dom-globals-in-react-fc | Disallow use of DOM globals in the render cycle of a React function component. | | | no-ds-tokens | Disallow any usage of --wpds-* CSS custom properties. | | | no-global-active-element | Disallow accessing the active element via document.activeElement. | ✓ | | no-global-get-selection | Disallow accessing the selection via window.getSelection. | ✓ | | no-setting-ds-tokens | Disallow setting any CSS custom property beginning with --wpds-. | ✓ | | no-unknown-ds-tokens | Prevent use of non-existing --wpds-* variables. | ✓ | | components-no-missing-40px-size-prop | Disallow missing __next40pxDefaultSize prop on @wordpress/components components. | ✓ | | components-no-unsafe-button-disabled | Disallow using disabled on Button without accessibleWhenDisabled. | ✓ | | no-unsafe-render-order | Prevent unsafe render composition orders that silently remove semantics. | ✓ | | no-i18n-in-save | Disallow translation functions in block save methods. | | | no-non-module-stylesheet-imports | Disallow importing non-module stylesheets from JavaScript files. | | | no-unmerged-classname | Disallow unmerged className in components that spread rest props. | | | no-unguarded-get-range-at | Disallow the usage of unguarded getRangeAt calls. | ✓ | | no-unsafe-wp-apis | Disallow the usage of unsafe APIs from @wordpress/* packages | ✓ | | use-recommended-components | Encourage the use of recommended UI components in a WordPress environment. | | | 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. | | | use-import-as | Enforce configured as names for specific named imports and unlocked private APIs. | | | valid-sprintf | Enforce valid sprintf usage. | ✓ | | wp-global-usage | Enforce correct usage of WordPress globals like globalThis.SCRIPT_DEBUG. | |

Migrating from eslintrc to flat config

If you are upgrading from a previous version that used .eslintrc.* files:

1. Replace your .eslintrc.* file with an eslint.config.mjs file.

2. Change extends arrays to import + spread:

   // Old (.eslintrc.js)
   module.exports = {
   	extends: [ 'plugin:@wordpress/eslint-plugin/recommended' ],
   };
   
   // New (eslint.config.mjs)
   import wordpress from '@wordpress/eslint-plugin';
   export default [ ...wordpress.configs.recommended ];

3. Convert overrides to separate config objects with files patterns.

4. Replace env with languageOptions.globals using the globals package.

5. Delete your .eslintignore file and move patterns into an ignores config object.

6. Update rule prefixes in inline comments: eslint-comments/* has been renamed to @eslint-community/eslint-comments/*. For example:

   - /* eslint-disable eslint-comments/no-unlimited-disable */
   + /* eslint-disable @eslint-community/eslint-comments/no-unlimited-disable */

7. Remove any /* eslint-env */ comments — they are no longer supported in ESLint v10. Use languageOptions.globals in your config instead.

For a comprehensive walkthrough with examples and troubleshooting, see the Gutenberg ESLint v10 migration guide. See also the ESLint migration guide for general flat config details.

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.