啟用 Prettier

Rush Stack 的lint 策略建議使用 Prettier 工具，以確保所有原始程式碼檔案的一致語法。採用此方法，ESLint 和 Prettier 具有互補的作用。

建議的 ESLint 用法

ESLint 強制執行一組程式碼慣例的規則。
範例：「函式名稱應以駝峰式大小寫開頭。」
修正這些問題可能會破壞測試或 API 合約。ESLint 可能會導致建置錯誤。
規則高度可自訂，不同的專案可能需要不同的規則。
因此，我們建議在建置專案時，針對每個專案資料夾分別叫用 ESLint。

建議的 Prettier 用法

Prettier 會標準化語法格式。
範例：縮排和逗號位置
修正這些問題絕不應影響程式碼的含義。Prettier 可以自動且隱藏地執行。
Prettier 不鼓勵自訂，一種慣例足以適用於整個儲存庫，甚至整個世界。
因此，我們建議針對整個儲存庫全域套用 Prettier。

在本文中，我們將示範如何設定 Prettier 在 git commit 期間自動執行。我們也建議開發人員安裝 VS Code 的 Prettier 擴充功能，該擴充功能會在您儲存時自動格式化檔案。

準備使用 Prettier

在開始設定 Git Hook 之前，首先我們需要設定 Prettier，並讓您現有的檔案美化。

由於 Prettier 將針對所有檔案執行，其設定檔位於儲存庫的根目錄。Prettier 允許此設定檔使用許多不同的名稱，但儘管有這麼大的彈性，其 JSON 剖析器仍會拒絕程式碼註解。因此，建議使用 .js 檔案副檔名。

<儲存庫根目錄>/.prettierrc.js

// Documentation for this file: https://prettier.dev.org.tw/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 Hook 會隱含地篩選任何未提交至 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 Hook 需求

讓我們設定一個 Git Hook，以便在變更提交時自動叫用 Prettier。

請記住，git commit 指令是核心作業，必須始終快速且可靠：開發人員可能想要在未先執行 rush install 的情況下對其分支進行提交。在某些情況下，無法執行 rush install，因為分支可能處於部分運作狀態。看來我們的 Git Hook 不應依賴常用的單一儲存庫安裝機制。

我們可以透過使用 Rush 的 install-run.js 指令碼，以依需求安裝 Prettier 套件來解決此問題。但事實證明，我們需要一起安裝多個依賴項目

pretty-quick：為了加快作業速度，我們將使用 pretty-quick 來計算要提交的已暫存檔案子集。只需要處理這些檔案。Prettier 無法執行此部分，因為它不與 Git 介接。
prettier：pretty-quick 工具具有 Prettier 套件的對等依賴。
選用外掛程式：如果您使用任何 Prettier 的外掛程式，則需要讓 prettier 套件可解析這些外掛程式。

在這種情況下，Rush 的「自動安裝程式」功能提供了 install-run.js 的便利替代方案。

啟用 Git Hook

首先，使用 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 Hook，以便在執行 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
若要實際安裝 Hook，請執行 rush install。
在最終合併您的 PR 之前，您可能想要最後一次執行 prettier . --write，以重新格式化在我們安裝 Hook 之前可能已修改的任何檔案。

您完成了！現在，每當變更提交至 Git 時，它們都會自動美化。

安裝 prettier 外掛程式

Prettier 支援外掛，可以新增新的語言或格式化規則。如果您選擇在設定中新增 Prettier 外掛，必須特別注意，確保所有可能呼叫 Prettier 的工具都能載入您的 Prettier 設定。

如上述步驟設定的 rush prettier
設定為儲存時格式化的編輯器（VSCode、Webstorm、Sublime 等）
使用 Prettier 格式化快照的 Jest 和 Heft 測試

這裡有一個使用 prettier-plugin-packagejson 外掛的範例

首先，將外掛套件新增到您的自動安裝程式 package.json 檔案中 -- 如果按照上述方式設定，這將會是 common/autoinstallers/rush-prettier/package.json。
```
{
  "dependencies": {
    "prettier-plugin-packagejson": "^2.2.18"
  }
}
```

更新您自動安裝程式的 lockfile

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 hooks 後自行修復，但每當您以這種方式更新 Prettier 外掛時，最好通知您的團隊。

準備使用 Prettier​

Git Hook 需求​

啟用 Git Hook​

安裝 prettier 外掛程式​

準備使用 Prettier

Git Hook 需求

啟用 Git Hook

安裝 prettier 外掛程式