eslint-config-alloy配置個性化ESLint規則的最佳參考

dmyz3214382發表於2024-03-09
EsLint

eslint-config-alloy

最新特性：eslint-config-alloy 現已支援 TypeScript 5.0
如果你使用的是 TypeScript 4.0，請安裝舊版 npm install --save-dev eslint-config-alloy@4

最新特性：eslint-config-alloy 現已支援 Vue 3.0
如果你使用的是 Vue 2.0，請安裝舊版 npm install --save-dev eslint-config-alloy@3

AlloyTeam ESLint 規則不僅是一套先進的適用於 React/Vue/Typescript 專案的 ESLint 配置規範，而且也是你配置個性化 ESLint 規則的最佳參考。

快速開始

請根據你的專案使用的技術棧選擇以下配置：

  • 內建規則
  • React
  • Vue
  • TypeScript
  • TypeScript React
  • TypeScript Vue

設計理念

  • 樣式相關的規則交給 Prettier 管理
  • 傳承 ESLint 的理念，幫助大家建立自己的規則
  • 高度的自動化：先進的規則管理，測試即文件即網站
  • 與時俱進，第一時間跟進最新的規則
詳細說明

樣式相關的規則交給 Prettier 管理

Prettier 是一個程式碼格式化工具，相比於 ESLint 中的程式碼格式規則，它提供了更少的選項，但是卻更加專業。

如今 Prettier 已經成為前端專案中的必備工具，eslint-config-alloy 也沒有必要再去維護 ESLint 中的程式碼格式相關的規則了，所以我們在 v3 版本中徹底去掉了所有 Prettier 相關的規則，用 ESLint 來檢查它更擅長的邏輯錯誤。

至於縮排要兩個空格還是四個空格，末尾要不要分號，可以在專案的 .prettierrc.js 中去配置，當然我們也提供了一份推薦的 Prettier 配置供大家參考。

傳承 ESLint 的理念，幫助大家建立自己的規則

大家還記得 ESLint 是怎麼打敗 JSHint 成為最受歡迎的 js 程式碼檢查工具嗎？就是因為 ESLint 推崇的外掛化、配置化，滿足了不同團隊不同技術棧的個性的需求。

所以 eslint-config-alloy 也傳承了 ESLint 的設計理念，不會強調必須要使用我們這套規則，而是透過文件、示例、測試、網站等方便大家參考 alloy 的規則，在此基礎上做出自己的個性化。

由於 React/Vue/TypeScript 外掛的文件沒有中文化（或中文的版本很滯後），所以 alloy 的文件很大程度上幫助了國內開發者理解和配置個性化的規則。

實際上國內有很多團隊或個人的 ESLint 配置，都參考了 alloy 的文件。

高度的自動化：先進的規則管理，測試即文件即網站

無情的推動自動化

eslint-config-alloy 透過高度的自動化，將一切能自動化管理的過程都交給指令碼處理，其中包括了：

  • 透過 GitHub Actions，自動每週檢查 ESLint 及相關外掛是否有新版本，新版本中是否有新規則需要我們新增
  • 自動檢查我們的規則是否包含了 Prettier 的規則
  • 自動檢查我們的規則是否包含了已廢棄（deprecated）的規則

除此之外，透過自動化的指令碼，我們甚至可以將成百上千個 ESLint 配置檔案分而治之，每個規則在一個單獨的目錄下管理：

  • 透過指令碼將單個的配置整合成最終的一個配置
  • 透過指令碼將單個配置中的 description 和 reason 構建成文件網站，方便大家檢視
  • 透過指令碼將單個配置中的 bad.js 和 good.js 輸出到網站中，甚至可以直接在網站中看到 bad.js 的（真實執行 ESLint 指令碼後的）報錯資訊

這樣的好處是顯而易見的，測試即文件即網站，我們可以只在一個地方維護規則和測試，其他工作都交給自動化指令碼，極大的降低了維護的成本。簡單來說，當我們有個新規則需要新增時，只需要寫三個檔案 test/index/another-rule/.eslintrc.js, test/index/another-rule/bad.js, test/index/another-rule/good.js 即可。

與時俱進，第一時間跟進最新的規則

ESLint 的更新很快，幾乎每週都有一個新版本，有時有新規則，有時會廢棄已有規則，而且相關外掛（React/Vue/TypeScript）也會時而更新，沒有自動化工具的話，實在是難以跟進。

而 eslint-config-alloy 透過上述的自動化工具，可以在第一時間就收到 GitHub Actions 的通知，告訴我們哪些規則需要新增：

這樣就實現了，在前端社群快速更迭的時候能夠及時跟進最新的規則，永遠保持 eslint-config-alloy 的活力和先進。

使用方法

內建規則

npm install --save-dev eslint @babel/core @babel/eslint-parser eslint-config-alloy

在你的專案的根目錄下建立一個 .eslintrc.js 檔案，並將以下內容複製進去：

module.exports = {
  extends: [
    'alloy',
  ],
  env: {
    // 你的環境變數（包含多個預定義的全域性變數）
    //
    // browser: true,
    // node: true,
    // mocha: true,
    // jest: true,
    // jquery: true
  },
  globals: {
    // 你的全域性變數（設定為 false 表示它不允許被重新賦值）
    //
    // myGlobal: false
  },
  rules: {
    // 自定義你的規則
  },
};

React

npm install --save-dev eslint @babel/core @babel/eslint-parser @babel/preset-react@latest eslint-plugin-react eslint-config-alloy

在你的專案的根目錄下建立一個 .eslintrc.js 檔案，並將以下內容複製進去：

module.exports = {
  extends: [
    'alloy',
    'alloy/react',
  ],
  env: {
    // 你的環境變數（包含多個預定義的全域性變數）
    //
    // browser: true,
    // node: true,
    // mocha: true,
    // jest: true,
    // jquery: true
  },
  globals: {
    // 你的全域性變數（設定為 false 表示它不允許被重新賦值）
    //
    // myGlobal: false
  },
  rules: {
    // 自定義你的規則
  },
};

Vue

npm install --save-dev eslint @babel/core @babel/eslint-parser vue-eslint-parser eslint-plugin-vue eslint-config-alloy

在你的專案的根目錄下建立一個 .eslintrc.js 檔案，並將以下內容複製進去：

module.exports = {
  extends: [
    'alloy',
    'alloy/vue',
  ],
  env: {
    // 你的環境變數（包含多個預定義的全域性變數）
    //
    // browser: true,
    // node: true,
    // mocha: true,
    // jest: true,
    // jquery: true
  },
  globals: {
    // 你的全域性變數（設定為 false 表示它不允許被重新賦值）
    //
    // myGlobal: false
  },
  rules: {
    // 自定義你的規則
  },
};

TypeScript

npm install --save-dev eslint typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-config-alloy

在你的專案的根目錄下建立一個 .eslintrc.js 檔案，並將以下內容複製進去：

module.exports = {
  extends: [
    'alloy',
    'alloy/typescript',
  ],
  env: {
    // 你的環境變數（包含多個預定義的全域性變數）
    //
    // browser: true,
    // node: true,
    // mocha: true,
    // jest: true,
    // jquery: true
  },
  globals: {
    // 你的全域性變數（設定為 false 表示它不允許被重新賦值）
    //
    // myGlobal: false
  },
  rules: {
    // 自定義你的規則
  },
};

TypeScript React

npm install --save-dev eslint typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-plugin-react eslint-config-alloy

在你的專案的根目錄下建立一個 .eslintrc.js 檔案，並將以下內容複製進去：

module.exports = {
  extends: [
    'alloy',
    'alloy/react',
    'alloy/typescript',
  ],
  env: {
    // 你的環境變數（包含多個預定義的全域性變數）
    //
    // browser: true,
    // node: true,
    // mocha: true,
    // jest: true,
    // jquery: true
  },
  globals: {
    // 你的全域性變數（設定為 false 表示它不允許被重新賦值）
    //
    // myGlobal: false
  },
  rules: {
    // 自定義你的規則
  },
};

TypeScript Vue

建議使用 npm init vue@3 建立整合了 Vue, TypeScript 和 ESLint 的專案，然後再參考此示例調整其 ESLint 配置。

常規方法如下：

npm install --save-dev @babel/core @babel/eslint-parser @typescript-eslint/eslint-plugin @typescript-eslint/parser @vue/eslint-config-typescript eslint eslint-config-alloy eslint-plugin-vue vue-eslint-parser

在你的專案的根目錄下建立一個 .eslintrc.js 檔案，並將以下內容複製進去：

module.exports = {
  extends: ['alloy', 'alloy/vue', 'alloy/typescript'],
  parser: 'vue-eslint-parser',
  parserOptions: {
    parser: {
      js: '@babel/eslint-parser',
      jsx: '@babel/eslint-parser',

      ts: '@typescript-eslint/parser',
      tsx: '@typescript-eslint/parser',

      // Leave the template parser unspecified, so that it could be determined by `<script lang="...">`
    },
  },
  env: {
    // Your environments (which contains several predefined global variables)
    //
    // browser: true,
    // node: true,
    // mocha: true,
    // jest: true,
    // jquery: true
  },
  globals: {
    // Your global variables (setting to false means it's not allowed to be reassigned)
    //
    // myGlobal: false
  },
  rules: {
    // Customize your rules
  },
};

常見問題

在 VSCode 中使用

在 VSCode 中安裝 ESLint 擴充套件即可。

參考這裡可以對擴充套件進行配置。

儲存時自動修復 ESLint 錯誤

如果想要開啟「儲存時自動修復」的功能，你需要配置 .vscode/settings.json：

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
}

如何結合 Prettier 使用

eslint-config-alloy 從 v3 開始，已經不包含所有樣式相關的規則了，故不需要引入 eslint-config-prettier。只需要安裝 prettier 及相關 VSCode 外掛即可。

AlloyTeam 提供了一套 Prettier 配置，你可以建立一個 .prettierrc 檔案，直接複用此配置：

"eslint-config-alloy/.prettierrc.js"

VSCode 的一個最佳實踐就是透過配置 .vscode/settings.json 來支援自動修復 Prettier 和 ESLint 錯誤：

{
  "files.eol": "\n",
  "editor.tabSize": 2,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

常用命令

# 安裝依賴
pnpm i
# 構建 index.js react.js 等 eslintrc 配置
pnpm build
# 執行測試
pnpm test
# 自動修復格式錯誤
pnpm prettier:fix
# 檢查是否覆蓋了所有的規則
pnpm rulesCoverage
# 釋出新版本
npm version <major|minor|patch>
git push --follow-tags
npm publish

Q & A

為什麼要重複造輪子

其實我們團隊最開始使用 airbnb 規則，但是由於它過於嚴格，部分規則還是需要個性化，導致後來越改越多，最後決定重新維護一套。經過四年多的打磨，現在 eslint-config-alloy 已經非常成熟與先進，也受到了公司內外很多團隊的歡迎。

為什麼不用 standard

standard 規範認為大家不應該浪費時間在個性化的規範了，而應該整個社群統一一份規範。這種說法有一定道理，但是它是與 ESLint 的設計理念背道而馳的。大家還記得 ESLint 是怎麼打敗 JSHint 成為最受歡迎的 js 程式碼檢查工具嗎？就是因為 ESLint 推崇的外掛化、配置化，滿足了不同團隊不同技術棧的個性的需求。

所以 eslint-config-alloy 也傳承了 ESLint 的設計理念，不會強調必須要使用我們這套規則，而是透過文件、示例、測試、網站等方便大家參考 alloy 的規則，在此基礎上做出自己的個性化。

由於 React/Vue/TypeScript 外掛的文件沒有中文化（或中文的版本很滯後），所以 alloy 的文件很大程度上幫助了國內開發者理解和配置個性化的規則。

實際上國內有很多團隊或個人公開的 ESLint 配置，都參考了 alloy 的文件。

相比於 airbnb 規則有什麼優勢

  1. eslint-config-alloy 擁有官方維護的 vue、typescript、react+typescript 規則，相比之下 airbnb 的 vue 和 typescript 都是第三方維護的
  2. 先進性，保證能夠與時俱進，前面已經重點提到了
  3. 方便個性化定製，包含中文講解和網站示例

你這個確實很好，我還是會選擇 airbnb

沒關係，eslint-config-alloy 從設計理念上就相信不同團隊不同專案可以有不同的配置，雖然你選擇使用 airbnb，但是當你有個性化配置需求的時候，還是可以來我們網站上參考一下哦~

參考

  • Alloyteam Code Guide
  • ESlint Code Guide
  • ESlint Shareable Config

相關文章