Rush Stack商店博客活动
跳至主要内容

使用 Rig 包

在大型环境中，许多项目最好使用完全相同的 Heft 配置进行构建。可能存在一些细微差异 - 例如，Node.js 项目可能发出 CommonJS 模块，而 Web 应用程序项目可能需要发出 ESNext 模块。但通常，一小部分通用的“配置文件”将涵盖大多数项目。 @rushstack/rig-package 系统提供了一种正式机制，用于将通用设置移入一个 NPM 包，该包会被添加到使用它的项目的 "devDependencies" 中。这被称为 **Rig 包**。请注意，同一个 NPM 包可能包含几个不同的 **Rig 配置文件**；每个配置文件都是包含一组配置文件的文件夹。

一些具体示例​

Heft 还提供了两个标准 Rig 包，您可以在项目中使用它们

按照这些示例，也很容易定义自己的自定义 Rig 包。

heft-node-rig-tutorial 示例项目说明了如何使用 @rushstack/heft-node-rig。

Rigging 原则​

@rushstack/rig-package 定义了“Rigging”概念，但只提供了一个 API，用于根据 **rig.json** 配置文件解析文件路径。将 Rigging 移植到现有工具需要超出此 API 的额外逻辑，并且可能需要针对不同工具进行不同的实现。Heft 已经为其官方插件实现了这种逻辑，但是如果您有使用 Heft 之外的其他工具链的项目，您可以通过复制与 Heft 相同的方法来使它们可 Rigging。

Rigging 包含三个不同的功能

1. 用于 "extends" 的基础文件​

许多配置文件提供了一个从另一个文件继承共享设置的功能，这是一种从 Rig 重用配置的简便方法。例如，在我们的示例项目中，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 包继承

  • **.eslintrc.js**，用于 lint 任务，前提是您使用 @rushstack/eslint-patch 解决方法或 @rushstack/eslint-config 规则集（包括该修补程序）
  • **config/api-extractor.json**，用于 api-extractor 任务
  • **config/jest.config.json**，用于 jest 任务；Jest 通常使用 "preset" 字段进行继承，但它有一些问题，因此 Heft 用 @rushstack/heft-config-file 引擎替换了 Jest 的配置文件加载器，然后我们使用 "extends" 而不是 "preset"。在所有其他方面，此文件都具有标准的 Jest 格式。
  • **tsconfig.json**，用于 typescript 任务
  • **webpack.config.js** 没有明确支持继承，但作为 JavaScript 模块，它可以调用 require() 来加载共享设置。

2. 可 Rigging 的配置文件​

虽然 "extends" 使文件变小，但它无法完全消除它们。 **rig.json** 文件可以完全消除大多数 Heft 配置文件。我们说这些文件是“可 Rigging”的配置文件。以下来自 heft-node-rig-tutorial 项目的示例

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

// The "rig.json" file directs tools to look for their config files in an external package.
// Documentation for this system: https://npmjs.net.cn/package/@rushstack/rig-package
{
  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",

  /**
   * (Required) The name of the rig package to inherit from.
   * It should be an NPM package name with the "-rig" suffix.
   */
  "rigPackageName": "@rushstack/heft-node-rig"

  /**
   * (Optional) Selects a config profile from the rig package.  The name must consist of
   * lowercase alphanumeric words separated by hyphens, for example "sample-profile".
   * If omitted, then the "default" profile will be used."
   */
  // "rigProfile": "your-profile-name"
}

**rig.json** 文件告诉 Heft，如果它在 **heft-node-rig-tutorial/config** 中找不到文件，它应该尝试在 **@rushstack/heft-node-rig/profiles/default/common** 文件夹中查找。

“可 Rigging”配置文件的示例

  • <项目文件夹>/config/api-extractor-task.json
  • <项目文件夹>/config/heft.json
  • <项目文件夹>/config/typescript.json

我们无法完全消除 **tsconfig.json**，因为 VS Code 等工具期望在项目的根文件夹中找到此文件。这一点对于 **.eslintrc.js** 等其他一些文件也是如此。在本网站上，每个配置文件的文档都指定了它是否可 Rigging。

3. 可 Rigging 的依赖项​

Rig 包还可以提供 NPM 依赖项，以避免必须为项目将它们指定为 "devDependencies"。以下工具包可以由 Rig 提供（前提是它们不需要作为其他项目依赖项的 peerDependencies）

  • @microsoft/api-extractor
  • eslint
  • jest 及其相关包
  • tslint
  • typescript
  • webpack 及其加载器和插件

通过 Rig 提供依赖项是可选的。本地项目的 devDependencies 优先于 Rig。

Heft 使用以下步骤独立解析每个可 Rigging 的工具

  1. 如果工具包在本地项目的 devDependencies 中列出，则该工具将从当前项目文件夹解析。（此步骤不考虑 dependencies 或 peerDependencies。）

  2. 否则，如果当前项目有 **rig.json** 文件，并且如果 Rig 的 **package.json** 在其 dependencies 中列出了该工具，则该工具将从 Rig 包文件夹解析。（此步骤不考虑 devDependencies 或 peerDependencies。）

  3. 否则，该工具将从当前项目文件夹解析。如果在该文件夹中找不到该工具，则会报告错误。

另请参阅​