WordPress VIP ESLint 插件
这是提供WordPressVIP(内部)JavaScript和TypeScript编码标准的ESLint插件. 它的灵感和借自 @wordpress/eslint-plugin。 。 。 .
安装
安装 eslint 财务报告和审定财务报表 @automattic/eslint-plugin-wpvip 你的项目.
npm install --save-dev eslint @automattic/eslint-plugin-wpvip
ESLint 9 (英语)^9.39.1)和ESLint 10支持.
当您的工程也安装时, 可选集成会自动检测 typescript, (中文(简体) ), jest, (中文(简体) ), react,或 prettier。这些软件包被宣布为可选的对等依赖,这样消费者就可以选择进入他们实际使用的堆栈.
ESLint 10 (英语)
eslint-plugin-jsx-a11y 财务报告和审定财务报表 eslint-plugin-react 与 ESLint 10 合作( 此插件 shims) eslint-plugin-react 与 @eslint/compat)),但他们还没有发布宣布ESLint 10在同行依赖性中的发布. 为了避免 ERESOLVE npm 出错, 请在您的工程中添加这些覆盖 package.json。 。 。 . $eslint 指您的项目本身 eslint 输入,所以 eslint 必须直接在 devDependencies (或 dependencies:
"overrides": {
"eslint-plugin-jsx-a11y": { "eslint": "$eslint" },
"eslint-plugin-react": { "eslint": "$eslint" }
}
升级到 2. 0
2.0 添加 ESLint 10 支持并包含这些断开更改 :
eslint-plugin-import改为:eslint-plugin-import-x。 。 。 . 登记在import命名空间, 因此规则 ID 如import/order财务报告和审定财务报表eslint-disable评论意见不变。 不过:- 设置现在使用
import-x/前缀.import/*设置( e)import/resolver, (中文(简体) ),import/internal-regex, (中文(简体) ),import/core-modules,)被忽略;例如重命名它们.import/resolver→import-x/resolver。 。 。 . - 不注册
eslint-plugin-import下级import自己; ESLint 会扔Cannot redefine plugin "import"。 。 。 . import/enforce-node-protocol-usage不存在于eslint-plugin-import-x; 从您的配置中删除 .eslint-plugin-import不再安装此软件包。 如果你的配置需要它, 添加到自己的devDependencies。 。 。 .
- 设置现在使用
- JavaScript 文件用 ESLint 的默认解析器( espree) 解析 改为
@babel/eslint-parser。您的项目中的 Babel 配置已不再应用,因此,只有 Babel 理解的语法(例如流或遗留的装饰)不支持parserOptions.babelOptions编号 :requireConfigFile被忽略。 ECMAScript版本遵循了ESLint的默认(latest),因此是新的内置全球(例如.SuppressedError, (中文(简体) ),Iterator) 被确认. - 已折旧的核心格式规则已移入
@stylistic/eslint-plugin。 。 。 . ESLint正在删除其格式规则,所以formatting, (中文(简体) ),javascript财务报告和审定财务报表react现在使用的配置@stylistic/*配置相同选项的规则(例如:.indent→@stylistic/indent, (中文(简体) ),func-call-spacing→@stylistic/function-call-spacing) (中文(简体) ). 重命名任何覆盖或eslint-disable对这些规则的评论;凌驾于旧的核心名称之上不再有任何效果.no-new-symbol改为:no-new-native-nonconstructor。 。 。 .- 结果并不总是相同的:
@stylistic在被冻结的核心规则中修正错误。 值得注意的是,@stylistic/indent现在检查其缩进混合标签和空格的行( 核心)indent跳过他们,比如结束}编号 :)编号 :]缩入标签外加两个空格,缩入链式任务(a = b = c不一样 只有格式化规则有效,即不使用prettier装潢,这关了他们. - 此软件包登记册
@stylistic/eslint-plugin下级@stylistic。如果您的配置同时注册,请确保 npm 解决同一副本(兼容的版本范围),否则 ESLint 将丢弃Cannot redefine plugin "@stylistic"。 。 。 .
- 结果并不总是相同的:
- 这个
jsdoc配置 不再启用jsdoc/newline-after-description,从中移除eslint-plugin-jsdoc使配置无法装入. - ESLint 语录
^9.39.1或者说^10.0.0需要时间 (先前为^9.7.0) (中文(简体) ). - 节点.js
^22.22.2 || >=24.15.0需要时间,包括使用ESLint 9(Node.js 20是报废).eslint-plugin-jsdoc65 要求这些版本;@stylistic/eslint-plugin仅限无害环境管理,并装入require(),这需要节点的内置require(esm)支助,和@eslint/compat(用于支持)eslint-plugin-reacteSLint 10)需要节点.js 20.19+/ 22.13+.
捐款
见 捐款额 关于开发、测试、出版等的详细情况.
配置
创建一个 eslint.config.cjs 文档。 这个 .cjs 扩展让节点js把它当作普通JS,即使您 package.json 已经 "type": "module"。本 README 中的例子使用此文件 :
const wpvip = require( '@automattic/eslint-plugin-wpvip' );
module.exports = [ ...wpvip.configs.recommended ];
就这样! 它与大多数JavaScript和TypeScript项目自动工作.
这个 typescript, (中文(简体) ), testing, (中文(简体) ), react,以及 prettier 页:1 recommended 仅在安装相应的软件包时才加载。 如果你需要那些可选的配置 解决在前面而不是何时 recommended 已装入,需要 init 先说 它使用相同的检测 recommended,所以其软件包未安装的可选集仍然被跳过:
require( '@automattic/eslint-plugin-wpvip/init' );
配置用于与ESLint合作的代码编辑器会自动取出规则并标出任何错误或警告.
如果您的工程只使用 JavaScript, 您不需要安装可选的对等器 。 如果使用模块 typescript, (中文(简体) ), testing, (中文(简体) ), react,或 prettier 直接配置,首先在工程中安装相应的软件包.
要跳过文件或路径,请添加配置对象 ignores (例如 { ignores: [ 'dist/**' ] })到数组.
软件包脚本可以用于自动运行林入和格式化命令. 这里有一些你项目的建议脚本 package.json- 只复制那些对你有用的。 这个 cmd: 脚本帮助您不重复动词 CLI 参数来作曲命令.
{
"scripts": {
"cmd:format": "prettier '**/*.(js|json|jsx|md|ts|tsx|yml|yaml)'",
"cmd:lint": "eslint",
"format": "npm run cmd:format -- --write",
"format:check": "npm run cmd:format -- --check",
"lint": "npm run cmd:lint .",
"lint:fix": "npm run cmd:lint . -- --fix",
"lint:ignore-warnings": "npm run cmd:lint . -- --quiet"
}
}
说明: ESLint 读取忽略图案 ignores 键入 eslint.config.cjs; 重复使用 .gitignore,参见 includeIgnoreFile。Pretier 自动忽略在 .prettierignore 或者可以瞄准目标 .gitignore 使用 --ignore-path。 。 。 .
建议配置
"推荐"配置包括JavaScript,TypeScript,Jest,和React的规则,包括与格式化和白色空间有关的规则. 这是要严格! 有观点的默认会让我们的代码库保持一致,并减少我们在项目间进行上下文切换时所经历的摩擦.
当然,这个推荐的配置对于每个项目来说可能并不理想,所以可以自由地使用可用的模块配置来"自建". 建议的配置相当于:
const wpvip = require( '@automattic/eslint-plugin-wpvip' );
module.exports = [
...wpvip.configs.javascript,
...wpvip.configs.formatting,
...wpvip.configs.typescript, // when "typescript" is installed
...wpvip.configs.testing, // when "jest" is installed
...wpvip.configs.react, // when "react" is installed
...wpvip.configs.prettier, // when "prettier" is installed
];
注意配置的顺序可能很重要,因为它们可以包含覆盖. 特别重要的是增加: prettier 最后一个配置 .
高级
安装 WP 预演 v3.x 从其他格式化规则中受益:
npm i --save-dev --save-exact "prettier@npm:[email protected]"
此 repo 也提供了 Pretier 配置, 您可以使用以下选项 .prettierrc数字 :
"@automattic/eslint-plugin-wpvip/prettierrc"
关于最大利益,见 Pretier 在编辑器中保存启用格式的文件。这使得您可以在Pretier处理格式化时集中精力进行编码.
编辑器配置
编辑器配置 提供了额外的格式规则,并与Pretier合作良好. 复制 .editorconfig 文件 从这回转到你的项目.
国 际
这个 cli 配置允许某些行为通常与最佳做法相悖,但在生成 CLI 工具的代码库中有用:
module.exports = [ ...wpvip.configs.recommended, ...wpvip.configs.cli ];
如果你的项目不是一个CLI工具,但偶尔会孕育出孩子的过程,你可能不需要这个配置. 相反,只有在必要的情况下才禁用这些规则,并包含一个解释:
// Running a fixed, trusted command.
// eslint-disable-next-line security/detect-child-process
const { execSync } = require( 'child_process' );
请注意: console.log 仍然被禁止(这里请看一个解释) (中文(简体) ). 如果你是写一次性 节点脚本, 您可以禁用每个文件的规则 :
/* eslint-disable no-console */
联合来文文件
JSDoc被认为是可选的,尤其是与TypeScript和OpenAPI文档等更好的替代品相比. 如果你想强制使用JSDoc,请使用 jsdoc 配置 :
module.exports = [ ...wpvip.configs.recommended, ...wpvip.configs.jsdoc ];
请注意,规则需要 @param 财务报告和审定财务报表 @return 类型在 TypeScript 文件中得到放松.
"弱"的配置
这个插件为正在向更强标准过渡的遗留代码库提供了一些所谓的"弱"配置. 这些配置降级从 recommended 配置为警告 。 在代码编辑器和其他输出中仍然可以看到警告,但不会出错的集成工作流程.
这些配置用于临时用途,不应长期使用. 我们也不建议使用如下工具: 连接线 忽略错误或警告。 虽然意图是防止大规模的改变并缓慢地过渡到更强的标准,但效果通常是过渡会停滞并最终完全停止.
三"弱"相貌可知: weak-javascript, (中文(简体) ), weak-typescript,以及 weak-testing虽然总是欢迎就这一项目提出要求,但请认真考虑是否确实有必要在这些配置中增加规则。 理想的是,我们努力从这些配置中删除规则,直到不再需要它们.