RoadmapShopEvents
Skip to main content

使用 rig

大型项目下,在不同项目下使用完全相同的 Heft 配置十分常见。但也可能有一些差异 —— 例如,Node.js 项目生成 CommonJS 模块,然而 web 应用生成 ESNext 模块。但通常而言,一小撮相同的“配置文件”可以覆盖绝大部分项目。我们可以通过将通用配置移动到 NPM 包中,并将该包添加到 "devDependencies" 中避免重复。这就是 rig 包. 注意单个 NPm 包可能包含多个不同的 rig 档案,每个档案是一个包含一组配置文件的文件夹。

Heft 提供了两种标准的 rig 包,可以在你的项目中使用:

当然,定义自己的 rig 包也很简单。

heft-node-rig-tutorial 是一个介绍如何使用 @rushstack/heft-node-rig 的示例仓库。

让我们来看用 rig 包的影响构建的三种方式:

1. 针对 "extends" 的基础文件

许多配置文件提供了继承自另一个文件的功能。例如,在我们的示例项目中,TypeScript 的配置被减少到只有几行:

heft-node-rig-tutorial/tsconfig.json

{
"extends": "./node_modules/@rushstack/heft-node-rig/profiles/default/tsconfig-base.json",
"compilerOptions": {
"types": ["heft-jest", "node"]
}
}

大部分的设置源自 default 配置档案中的 tsconfig-base.json. 同时本地的 tsconfig.json 文件可以按需添加 "types" 等自定义设置。

以下配置文件都支持诸如 "extends" 的字段,以便设置可以从另一个 NPM 包继承配置:

2. "Riggable" 配置文件

在上面示例中,我们不能完全消除 tsconfig.json, 因为诸如 VS Code 等工具会在项目根目录下寻找该文件。对于 .eslintrc.js 等其他文件也是如此。除了这些特殊情况外,大多数其他的 Heft 配置文件可以通过创建一个 rig.json 来完全消除,示例可参考 heft-note-rig-tutorial 项目。

heft-node-rig-tutorial/config/rig.json

// "rig.json" 文件来指导不同的工具在外部包中寻找它们的对应配置文件。
// 关于该系统的文档可参考: https://www.npmjs.com/package/@rushstack/rig-package
{
"$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",

/**
* (必须)继承的 rig 包的名字。
* 它要求 NPM 包必须带有 "-rig" 的后缀。
*/
"rigPackageName": "@rushstack/heft-node-rig"

/**
* (可选) 从 rig 包的配置档案中选择一个。
* 该命名要求是一个小写字母,用连字符分割,例如 "sample-profile".
* 如果省略,则使用 "default" 配置档案
*/
// "rigProfile": "your-profile-name"
}

rig.json 文件告知 Heft, 如果在 heft-node-rig-tutorial/config 中没找到相应的配置,那么尝试 @rushstack/heft-node-rig/profiles/default/common 中进行寻找。

"riggable" 配置文件示例:

  • <project folder>/config/api-extractor-task.json
  • <project folder>/config/heft.json
  • <project folder>/config/typescript.json

3. Riggable 依赖

rig 包也提供了 NPM 依赖,为了避免在项目的 devDependencies 指定某些依赖。rig 已经提供了以下工具包:

  • typescript
  • @microsoft/api-extractor
  • eslint
  • tslint

目前,rig 只提供了这些包。通过 rig 来提供依赖是一个可选项,你本地项目的 devDependencies 优先于 rig.

Heft 通过以下方法来查找每个依赖:

  1. 如果本地项目内的某个依赖列在 devDependencies 中,那么这个工具将从当前文件夹下解析(该步骤不考虑 dependenciespeerDependencies)。

  2. 否则,如果当前项目存在 rig.json 文件,并且 rig 的 package.json 将工具列举在 dependencies 下,那么会从 rig 包的目录中解析这些工具(该步骤不考虑 devDependenciespeerDependencies)。

  3. 否则,会从当前项目的目录中解析工具,如果找不到,则会报错。

注意: 早于 0.25.0 的版本中,Heft 使用了 不同的查找策略, 该策略并不依赖 rig.json 文件,它的工作方式如下:当解析某个工程的 tsconfig.json 时, 如果它的 extends 字段指向了某个 NPM 包。Heft 会查看该包是否有直接依赖于 typescript, 如果依赖,那么将在该文件夹下解析所有的 riggable 工具。

Heft 本身直接依赖以下软件包,所以你的项目不需要依赖它们:

  • webpackwebpack-dev-server
  • jest 以及它的核心依赖

参考