@wordpress/eslint-plugin

查看官方原文 ↗

💡 云策文档标注

概述

@wordpress/eslint-plugin 是一个为 WordPress 开发提供的 ESLint 插件，包含配置和自定义规则。它支持 ESLint v10+ 的 Flat config 和旧版 eslintrc 格式，并提供了推荐预设和细粒度规则集。

关键要点

安装要求 Node.js 长期支持版本，通过 npm install @wordpress/eslint-plugin --save-dev 安装。
推荐使用 Flat config（ESLint v10+），在 eslint.config.mjs 中导入并扩展 wordpress.configs.recommended。
旧版 eslintrc（ESLint v9）支持已弃用，建议迁移到 Flat config。
推荐预设包含 ES2015+ 环境规则，并可选集成 eslint-plugin-prettier 和 @typescript-eslint/eslint-plugin。
提供细粒度规则集，如 custom、esnext、react 等，可按需组合使用。
自定义规则涵盖国际化、React 组件、数据存储、安全 API 使用等多个方面。
迁移指南帮助从 eslintrc 升级到 Flat config，包括文件替换和配置转换。
此包是 Gutenberg 项目的一部分，采用 monorepo 结构，欢迎贡献。

代码示例

// Flat config 示例 (ESLint v10+)
import wordpress from '@wordpress/eslint-plugin';

export default [
    ...wordpress.configs.recommended,
    {
        rules: {
            // 自定义规则覆盖
        },
    },
];

// 仅使用 ESNext 规则集示例
import wordpress from '@wordpress/eslint-plugin';

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

注意事项

确保 Node.js 版本为 Active LTS 或 Maintenance LTS，不兼容旧版本。
eslintrc 包装器已弃用，将在未来主要版本中移除，建议尽快迁移到 Flat config。
细粒度规则集不定义环境全局变量，如需使用需自行定义。
推荐预设中的 Prettier 和 TypeScript 集成是可选的，需单独安装 prettier 和 typescript 包激活。
迁移时需替换 .eslintrc.* 文件为 eslint.config.mjs，并调整配置语法。

📄 原文内容

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

Flat config (ESLint v10+, 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, 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;

Note: The eslintrc wrapper is deprecated and will be removed in a future major version. 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.
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-i18n-in-save	Disallow translation functions in block save methods.
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.
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:

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

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 ];

Convert overrides to separate config objects with files patterns.
Replace env with languageOptions.globals using the globals package.
Delete your .eslintignore file and move patterns into an ignores config object.

See the ESLint migration guide for full 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.

云策 WordPress 开发者社区

块编辑器开发文档