ESLint 的新规则格式

作为规则文档生成过程自动化的环节之一,ESLint 规则现在有了新的格式。我们解释了这种新格式的要素,以及如何自动将旧格式的规则转换为新格式。如果您是插件作者,建议您相应地更新您的自定义规则。

当 ESLint 在三年前开始时,它还是一个规模小得多的项目,用户群也小得多。自那时以来,该项目已经发展壮大了很多,为了帮助项目扩展,我们投入了大量时间来自动化尽可能多的流程。例如,我们的发布流程现在完全自动化,包括根据提交到发布中的内容来决定下一个版本号。当我们回顾仍然是手动流程的过程时,有一个过程非常突出,那就是:保持规则文档同步。当只有十几个规则时,这不是一个大问题,但随着规则数量超过 200 个,这个重复的过程已经变成了一项耗费大量时间的工作。

因此,我们第一次决定更改 ESLint 的规则格式。这次更改幅度很小,我们希望您会同意这样做很有意义。总体设计目标是允许将元数据直接存储在规则本身上。这样做使我们能够拥有规则相关元数据的单一事实来源,然后基于该元数据生成文档,例如我们的规则索引页面和各个规则的文档页面。这意味着,每当规则变得可修复或添加到 eslint:recommended 时,我们将不再需要手动更新多个文档页面。

我们经历了很多设计会议,才提出了一个新的规则格式,该格式对于现有的规则开发者来说易于使用——尽可能少地进行更改,使新格式与他们熟悉。

格式比较

首先,考虑一下 ESLint 中规则的传统外观

// the rule creator function
module.exports = function(context) {
// code
};

// the rule options schema
module.exports.schema = [];

此格式的两个关键部分是规则创建器函数和规则选项模式。可能很明显,我们最初没有规则选项模式,后来才添加它们。这导致了在 module.exports 上尴尬地包含 schema 对象。我们从来都不太喜欢这种设置,因为模式似乎应该在创建器函数之前定义,但是如果我们不更改整个规则格式(我们当时不想这样做),我们就没有太多选择。

新的规则格式应该看起来有点相似

module.exports = {

meta: {

// special key used for doc-only information
docs: {},

// indicates if the rule is fixable
fixable: "code",

// the rule options schema
schema: []
},

// the rule creator function
create: function(context) {
// code
}
};

规则创建器函数和规则选项模式仍然存在于这种新格式中。最大的区别在于导出一个对象,并且规则创建器函数是该对象上名为 create() 的方法。create() 的内容与旧格式中创建器函数的内容相同——您不必做任何不同的事情,因此您可以直接复制粘贴所有旧代码。

该对象还具有一个 meta 属性,其中包含规则的附加元数据,包括规则选项模式。此外,还有一个 docs 对象,其中包含用于我们的文档生成的信息,以及 fixable 属性,该属性仅在规则可修复时存在(提前知道规则是否可修复使我们能够优化自动修复过程,并在文档中突出显示这一点)。

您可以在 使用规则 中阅读有关新格式的更多信息。

自动转换

所有 ESLint 核心规则现在都已转换为新格式,我们建议插件作者也将其自定义规则更新为新格式。我们使用了一个现在可用的名为 eslint-transforms 的工具来自动将我们的旧式规则转换为新格式。您可以从 npm 安装该工具

$ npm install -g eslint-transforms

然后您可以像这样转换您的规则

$ eslint-transforms new-rule-format path/to/rules/ rule.js

您可以传入任意数量的文件或目录进行转换。有关更多信息,请参阅 repo

最新的 ESLint 新闻、案例研究、教程和资源。

Evolving flat config with extends
5 分钟阅读

使用 extends 进化扁平配置

您的 eslint.config.js 文件现在可以使用 extends 来简化您的配置。

ESLint v9.22.0 released
1 分钟阅读

ESLint v9.22.0 发布

我们刚刚推送了 ESLint v9.22.0,这是一个 ESLint 的小版本升级。此版本添加了一些新功能并修复了先前版本中发现的几个错误。

ESLint v9.21.0 released
2 分钟阅读

ESLint v9.21.0 发布

我们刚刚推送了 ESLint v9.21.0,这是一个 ESLint 的小版本升级。此版本添加了一些新功能并修复了先前版本中发现的几个错误。