启用 Prettier

The Rush Stack lint strategy recommends the Prettier tool for ensuring consistent syntax across all source files. With this approach, ESLint and Prettier have complementary roles

推荐的 ESLint 用法

ESLint 针对编码约定执行一组规则。
例如：“函数名应以驼峰式命名法大写。”
修复这些问题可能会破坏测试或 API 合同。ESLint 可能会导致构建错误。
规则高度可定制 - 不同的项目可能需要不同的规则。
因此，我们建议在构建每个项目时，为每个项目文件夹单独调用 ESLint。

推荐的 Prettier 用法

Prettier 规范化语法格式。
例如：缩进和逗号放置
修复这些问题绝不会影响代码的含义。Prettier 可以自动且不可见地运行。
Prettier 不鼓励定制 - 对于整个仓库来说，一个约定就足够了，如果不是整个世界的话。
因此，我们建议在整个仓库中全局应用 Prettier。

在本文中，我们将展示如何配置 Prettier 在 git commit 期间自动运行。我们还建议开发人员安装 VS Code 的 Prettier 扩展，该扩展在您保存时会自动格式化文件。

为 Prettier 做准备

在开始使用 Git 钩子之前，我们需要先配置 Prettier，并将现有文件格式化。

由于 Prettier 将为所有文件运行，因此其配置文件位于仓库的根目录。Prettier 允许此配置文件使用许多不同的名称，但尽管具有所有这些灵活性，其 JSON 解析器仍然拒绝代码注释。因此，建议使用 .js 文件扩展名。

<仓库根目录>/.prettierrc.js

// Documentation for this file: https://prettier.node.org.cn/en/configuration.html
module.exports = {
  // We use a larger print width because Prettier's word-wrapping seems to be tuned
  // for plain JavaScript without type annotations
  printWidth: 110,

  // Use .gitattributes to manage newlines
  endOfLine: 'auto',

  // Use single quotes instead of double quotes
  singleQuote: true,

  // For ES5, trailing commas cannot be used in function parameters; it is counterintuitive
  // to use them for arrays only
  trailingComma: 'none'
};

您还需要创建一个 .prettierignore 文件来告诉 Prettier 跳过哪些文件。请注意，Git 钩子会隐式过滤任何未提交到 Git 的文件，但这不适用于其他工具，例如 VS Code 的 Prettier 扩展。建议 .prettierignore 扩展 .gitignore 中使用的相同模式，如下所示

<仓库根目录>/.prettierignore

#-------------------------------------------------------------------------------------------------------------------
# Keep this section in sync with .gitignore
#-------------------------------------------------------------------------------------------------------------------

👋 (copy + paste your .gitignore file contents here) 👋

#-------------------------------------------------------------------------------------------------------------------
# Prettier-specific overrides
#-------------------------------------------------------------------------------------------------------------------

# Rush files
common/changes/
common/scripts/
common/config/
CHANGELOG.*

# Package manager files
pnpm-lock.yaml
yarn.lock
package-lock.json
shrinkwrap.json

# Build outputs
dist
lib

# Prettier reformats code blocks inside Markdown, which affects rendered output
*.md

配置好之后，接下来我们需要手动调用 Prettier 来重新格式化所有现有的源文件。您可以通过在执行此命令后检查 Git 差异来微调您的 .prettierignore 配置。

# Install prettier so you can invoke it manually
npm install --global prettier

# Run these commands from your repo root, since "." below refers to the current folder
cd my-repo

# See what files Prettier will operate on; use this to tune your .prettierignore rules
prettier . --list-different

# When you are ready, this will bulk fix all existing source files in your repo
prettier . --write

您第一次运行 Prettier 时，如果您的仓库中已经存在很多文件，它可能会生成一个非常大的差异。在这种情况下，最好合并一个只包含这些更改的 PR。这将使您更容易审查 PR 的后续步骤。

Git 钩子要求

让我们设置一个 Git 钩子，它会在每次提交更改时自动调用 Prettier。

请记住，git commit 命令是一个核心操作，它必须始终快速且可靠：开发人员可能希望在不先运行 rush install 的情况下将其更改提交到分支。在某些情况下，无法运行 rush install，因为分支可能处于部分工作状态。看来我们的 Git 钩子不应依赖于通常的 monorepo 安装机制。

我们可以通过使用 Rush 的 install-run.js 脚本按需安装 Prettier 包来解决此问题。但事实证明，我们需要一起安装多个依赖项

pretty-quick：为了加快操作速度，我们将使用 pretty-quick 来计算要提交的已暂存文件的子集。只需要处理这些文件。Prettier 无法执行此操作，因为它不与 Git 交互。
prettier：pretty-quick 工具对 Prettier 的包有一个对等依赖。
可选插件：如果您使用任何 Prettier 插件，则它们需要由 prettier 包解析。

对于这种情况，Rush 的“自动安装器”功能提供了一种方便的替代方法，可以替代 install-run.js。

启用 Git 钩子

首先，使用 rush init-autoinstaller 命令创建自动安装器

# This creates the common/autoinstallers/rush-prettier/package.json file:
rush init-autoinstaller --name rush-prettier

安装依赖项并创建 pnpm-lock.yaml 文件

cd common/autoinstallers/rush-prettier

# Instead of running these commands, you could instead manually edit the
# "dependencies" in the package.json file
pnpm install prettier
pnpm install pretty-quick

# (If you need plugins, install them as well)

# When you are finished, run this command to ensure that the
# common/autoinstallers/rush-prettier/pnpm-lock.yaml file is up to date
rush update-autoinstaller --name rush-prettier

您现在应该在 common/autoinstallers/rush-prettier 文件夹中拥有两个文件 package.json 和 pnpm-lock.yaml。将它们添加到 Git 并提交它们。
```
git add package.json
git add pnpm-lock.yaml
git commit -m "Create rush-prettier autoinstaller"
```

接下来，我们将创建一个 rush prettier 自定义命令来调用 pretty-quick 工具。将此添加到您的 command-line.json 文件的 "commands" 部分

common/config/rush/command-line.json

  . . .
  "commands": [
    {
      "name": "prettier",
      "commandKind": "global",
      "summary": "Used by the pre-commit Git hook. This command invokes Prettier to reformat staged changes.",
      "safeForSimultaneousRushProcesses": true,

      "autoinstallerName": "rush-prettier",

      // This will invoke common/autoinstallers/rush-prettier/node_modules/.bin/pretty-quick
      "shellCommand": "pretty-quick --staged"
    }
    . . .

"autoinstallerName": "rush-prettier" 行确保我们的自动安装器将在 shell 命令被调用之前安装 Prettier。shell 命令 pretty-quick --staged 将在 common/autoinstallers/rush-prettier 文件夹中被调用。

保存这些更改后，让我们通过运行 rush prettier 来测试我们的自定义命令。第一次运行时，您应该看到 Rush 自动执行许多步骤：(1) 安装正确的 Rush 引擎版本，(2) 安装正确的 PNPM 包管理器版本，(3) 安装 rush-prettier/package.json 及其依赖项，(4) 调用 pretty-quick --staged。但是您第二次调用它时，前 3 个步骤是最新的，因此步骤 (4) 会立即运行。很好！
因为 rush prettier 只处理已暂存以供提交的文件，所以报告很可能显示
```
Found 0 changed files.
Everything is awesome!
```

最后一步是添加一个 Git 钩子，它会在执行 git commit 时自动调用 rush prettier。为此，在 common/git-hooks 文件夹中创建一个名为 pre-commit 的文件

common/git-hooks/pre-commit

#!/bin/sh
# Called by "git commit" with no arguments.  The hook should
# exit with non-zero status after issuing an appropriate message if
# it wants to stop the commit.

# Invoke the "rush prettier" custom command to reformat files whenever they
# are committed. The command is defined in common/config/rush/command-line.json
# and uses the "rush-prettier" autoinstaller.
node common/scripts/install-run-rush.js prettier || exit $?

使文件可执行：chmod +x pre-commit
要实际安装钩子，请运行 rush install。
在最终合并您的 PR 之前，您可能需要再次运行 prettier . --write 来重新格式化可能在安装钩子之前修改过的任何文件。

您完成了！现在，每当更改提交到 Git 时，它们都会被自动格式化。

安装 prettier 插件

Prettier 支持插件，它们可以添加新的语言或格式化规则。如果您选择将 prettier 插件添加到您的设置中，则必须特别注意确保所有可能调用 prettier 的工具都能加载您的 prettier 配置

rush prettier，如上述步骤中配置的那样
配置为在保存时格式化的编辑器 (VSCode、Webstorm、Sublime 等)
Jest 和 heft 测试，它们使用 prettier 来格式化快照

以下是一个使用 prettier-plugin-packagejson 插件的示例

首先，将插件包添加到您的自动安装器 package.json 文件中 - 如果配置如上，则它将是 common/autoinstallers/rush-prettier/package.json。
```
{
  "dependencies": {
    "prettier-plugin-packagejson": "^2.2.18"
  }
}
```

更新您的自动安装器的锁文件

rush update-autoinstaller --name rush-prettier

将插件文件夹的完整路径添加到 .prettierrc.js 中的 plugins 数组中

module.exports = {
  // ... your other configuration goes here ...
  // ,

  plugins: ['./common/autoinstallers/rush-prettier/node_modules/prettier-plugin-packagejson']
};

提交您的自动安装器和 prettierrc 更改。

请注意，在拉取此更改后，本地开发人员需要至少运行一次rush prettier来安装更新的自动安装程序 - 否则，他们的保存时格式化功能和 jest 快照格式化可能会停止工作。在实践中，这将在他们执行至少一次 git 提交并运行 git 钩子后自行修复，但无论何时以这种方式更新 prettier 插件，您可能需要通知您的团队。

为 Prettier 做准备​

Git 钩子要求​

启用 Git 钩子​

安装 prettier 插件​

为 Prettier 做准备

Git 钩子要求

启用 Git 钩子

安装 prettier 插件