[note] ESLint

keywords: CLI

• Configuring ESLint @ ESLint > UserGuide > Configuring
• Configuration Files @ ESLint > UserGuide > Configuration
• ESLint Demo

Command Line Interface

Command Line Interface @ ESLint

# 安裝 eslint cli
$ npm i eslint

# 初始化 eslint 專案
$ npx eslint --init  # To check syntax, find problems, and enforce code style

# 執行 eslint
$ eslint [options] [file|dir|glob]*
$ eslint . --ext .jsx,.js,.ts,.tsx

# 檢視並複製當前套用到的 eslint config
$ npx eslint --print-config path::String | pbcopy

使用範例

# eslint [options] file.js [file.js] [dir]
$ eslint 'src/**/*.ts'   # 檢驗所有 src 中的 .ts 檔
$ eslint file1.js file2.js
$ eslint lib/**

修復問題

# Fixing problems:
#  --fix              自動修復問題
#  --fix-dry-run      自動修復問題，但不儲存檔案
$ eslint 'src/**/*.ts' --fix

透過 npm 執行

// package.json
"scripts": {
  "lint": "eslint src/**/*.ts"
}

執行：

$ npm run lint -- --fix

設定 ESLint

ESLint Configuration @ ESLint

設定方式

ESLint 有兩種最主要的設定方式：

1. 註解：在檔案中直接透過 JavaScript 的註解來進行設定
2. 設定檔：為整個專案進行設定，一樣有兩種設定方式
   • 使用 JavaScript、JSON 或 YAML 檔案來，它可以是 .eslintrc.* 的檔案
   • 或在 package.json 中使用 eslintConfig 這個欄位來進行設定

透過 ESLint CLI 可以快速建立設定檔。

定義規則（rules）

這裡的 semi 和 quotes 是 ESLint 中可以套用的規則（rules），陣列中的：

• 第一個值是「錯誤層級（error level）」：
  • off 或 0 - 關閉規則
  • warn 或 1- 將該規則顯示為警告，但仍可執行
  • error 或 2 - 將規則顯示為錯誤，會跳出錯誤後不執行，無法成功編譯
• 第二個值則是針對該規則的「設定」，例如在 semi 規則中的 always 表示總是要有分號；quotes 規則中的 double 則表示要使用雙引號。

// .eslintrc.*
{
  "rules": {
    "semi": ["error", "always"], // "semi": "error",
    "quotes": ["error", "double"],
    "no-console": "off"
  }
}

如果是針對第三方 plugins 要設定規則的話，最前面會戴上該 plugin 的名稱，例如：

// 針對 jest 這個 plugin 套用規則（要留意 jest 這個 plugin 需要在 "plugins" 或 "extends" 欄位中被啟用（activate）過。

{
  "rules": {
    "jest/no-disabled-tests": "warn",
    "jest/no-focused-tests": "error"
  }
}

定義解析選項（parser options）

keywords: parserOptions

設定 parser options 可以幫助 ESLint 決定什麼是解析錯誤，所有語言預設的選項都是 false。

預設的 ESLint 並沒有支援所有最新的 ES6 語法，因此若有需要可以加上 { "parserOptions": { "ecmaVersion": 6 } } 的設定。

相關的設定如下：

• ecmaVersion - 設成 3, 5 (default), 6, 7, 8, 9, 10 or 11 來指定要使用哪一版本的 ECMAScript 語法，也可以用年份寫 2015 等同於 6，2016 等同於 7，以此類推。

• sourceType - 設成 script (default) 或 module（如果你使用的是 ECMAScript modules）。

• ecmaFeatures - 用來定義希望使用語言中哪些額外的功能

  • globalReturn - 可以在 global scope 下使用 return
  • impliedStrict - 可以在全域使用 Strict Mode
  • jsx - 可以使用 JSX

// .eslintrc.json
{
  "parserOptions": {
    "ecmaVersion": 6,
    "sourceType": "module",
    "ecmaFeatures": {
      "jsx": true,
      "settings": {
        // 這裡可以設定 react 的版本
        "react": {
          "version": "16.13.1"
        }
      }
    }
  }
}

定義環境（environments）

keywords: env

Specifying Environments @ ESLint

透過定義環境可以讓 ESLint 中知道有哪些可用的環境變數或全域變數（global variable），例如，console.log, alert 等等。其中常見的選項包含 browser, node, commonjs，設定方式如下：

// .eslintrc.json
{
  "env": {
    "browser": true,
    "node": true,
    "es2021": true,
    "jest": true
  }
}

或者在 package.json 設定也可以：

// package.json
{
  "name": "my-package",
  "version": "0.0.1",
  "eslintConfig": {
    "env": {
      "browser": true,
      "node": true
    }
  }
}

設定全域變數（global environments）

透過 globals 欄位可以哪些變數是可以直接在檔案中使用的全域變數，設定方式如下：

// eslintrc.json

/**
 * 設定 var1 和 var2 為全域變數
 * writable 表示該變數可以被重新定義該變數
 * readonly 則不能重新定義該變數
 **/
{
  "globals": {
    "var1": "writable",
    "var2": "readonly"
  }
}

設定外掛（plugins）

在 ESLint 中可以使用第三方的套件，其中在使用這些套件前需要先透過 npm 進行安裝。在設定時，每個套件名稱前面的 eslint-plugin- 可以省略不寫：

// eslintrc.json
{
  "plugins": ["plugin1", "eslint-plugin-plugin2"]
}

延伸設定檔（Extending Configuration Files）

Extending Configuration Files @ ESLint Configuration

由 extends 延伸後的規則，可以在 rules 欄位中進行修改或覆蓋。

extends 的欄位可以是：

• 透過字串來定義設定檔
• 透過字串陣列（array of strings）來定義，每一個設定都會延伸自前一個設定檔

extends 的設定檔可以是「設定檔的路徑」或「共用的設定檔（shareable config）」，例如 eslint:recommended, eslint:all），同樣的套件名稱前面的 eslint-config- 可以省略。

// .eslintrc.js
// 透過 extends 擴增的規則可以再透過 rules 進行修改或覆蓋
module.exports = {
  extends: 'eslint:recommended',
  rules: {
    // enable additional rules
    indent: ['error', 4],
    'linebreak-style': ['error', 'unix'],
    quotes: ['error', 'double'],
    semi: ['error', 'always'],

    // override default options for rules from base configurations
    'comma-dangle': ['error', 'always'],
    'no-cond-assign': ['error', 'always'],

    // disable rules from base configurations
    'no-console': 'off',
  },
};

overrides

How does overrides work @ ESLint

overrides 則可以把規則套用在特定的檔案上。例如，下面的設定檔為例，會把規則套用在所有符合 .ts 和 .tsx 的檔案：

// .eslintrc.js
module.exports = {
  overrides: [
    {
      files: ['**/*.ts', '**/*.tsx'],
      // 各種規則...
    },
  ],
};

建立自己的 config

How to Create Your Own ESLint Config Package @ freecodecamp

程式碼中備註

整支檔案隱藏警告

keywords: eslint-disable, eslint {rule}: 0

忽略所有規則

放在檔案開頭：

/* eslint-disable */ // 在該檔案關閉 ESLint

忽略特定規則

// 放在檔案的最上方
/* eslint-disable [rule-name] */
/* eslint-disable no-alert, no-console

off or 0 - 關閉規則 warn or 1 - turn the rule on as a warning (doesn’t affect exit code) error or 2 - turn the rule on as an error (exit code is 1 when triggered)

/* eslint no-unused-vars: 0 */
/* eslint no-unused-vars: "error" */

/* global myVar1, myVar2 */ // 忽略未定義的全域變數

於 package.json 中設定

忽略特定的全域變數也可以在 package.json 中加上：

{
  "standard": {
    "globals": ["myVar1", "myVar2"]
  }
}

特定行數隱藏警告

keywords: eslint-disable-line, eslint-disable-next-line, eslint-disable-line {rule}, eslint-disable-next-line {rule}

忽略單行

忽略所有規則

file = 'I know what I am doing'; // eslint-disable-line

// eslint-disable-next-line
alert('foo');

忽略特定規則

alert('foo'); // eslint-disable-line no-alert, quotes, semi

// eslint-disable-next-line no-alert
alert('foo');

忽略多行

keywords: eslint-disable, eslint-enable

忽略所有規則

/* eslint-disable */
alert('foo');
/* eslint-enable */

忽略特定規則

/* eslint-disable no-alert, no-console */
alert('foo');
console.log('bar');
/* eslint-enable no-alert, no-console */

TypeScript

在 JS 的專案中使用 TS

當專案中 JS 檔和 TS 檔並存時，可以使用 ESLint 提供的 overrides 方法，保持原本對 JS lint 的規則，針對 TS 檔再套用其他規則：

module.exports = {
  /* 原本針對 JS 寫的 eslint 設定... */

  // overrides 中填寫針對 TS 的 ESLint 設定
  overrides: [
    {
      files: ['./**/*.ts', './**/*.tsx'],
      parser: '@typescript-eslint/parser',
      plugins: ['@typescript-eslint', 'simple-import-sort'],
      extends: [
        /* ... */
      ],
      rules: {
        /* ... */
      },
    },
  ],
};

@typescript-eslint

必看：

• Getting Started - Linting your TypeScript Codebase
• Getting Started - Linting with Type Information
• Troubleshooting / FAQ

TL;DR

• TypeScript 是使用 tsc 來編譯 TypeScript 檔案，會吃到的設定檔是 tsconfig.json。當在 VSCode 中看到 ts 的錯誤時，就是由 tsc 產生。
• tsconfig.eslint.json 是給 @typescript-eslint 吃的 tsconfig 檔，它會繼承 tsconfig.json。當在 VSCode 中出現 @typescript-eslint 的錯誤就是由它產生的。
• 出現 Parsing error: "parserOptions.project" has been set for @typescript-eslint/parser. 的錯誤時，表示 ESLint 想要解析的檔案並沒有被列在給 @typescript-eslint 所涵括到的檔案中。

所有規則

• rules @ typescript-eslint-plugin

有些 ESLint 內建的規則需要先被關掉

I am using a rule from ESLint core, and it doesn't work correctly with TypeScript code @ TypeScript ESLint Q & A

// .eslintrc
{
  "rules": {
    // note you must disable the base rule as it can report incorrect errors
    "no-use-before-define": "off",
    "@typescript-eslint/no-use-before-define": [
      "error",
      { "functions": false, "classes": true, "variables": true, "typedefs": true }
    ]
  }
}

@typescript-eslint/ban-types

• ban-types @ Github
• allow selective disable of default options with false value @ GitHub PR

如果只想要關掉對於 {} 的警告：

// .eslintrc
// https://github.com/typescript-eslint/typescript-eslint/pull/2137

{
  "types": {
    "{}": false
  },
  "extendDefaults": true
}

Parsing error: "parserOptions.project" has been set for @typescript-eslint/parser

官方文件

• Linting with Type Information
• I get errors telling me "ESLint was configured to run ... However, that TSConfig does not / none of those TSConfigs include this file"

錯誤描述：

error  Parsing error: "parserOptions.project" has been set for @typescript-eslint/parser.
The file does not match your project config: .eslintrc.js.
The file must be included in at least one of the projects provided

問題原因：

當開啟 'plugin:@typescript-eslint/recommended-requiring-type-checking' 時，@typescript-eslint 會使用 tsconfig 的設定，並對型別做出檢查。這時候tsconfig 會編譯到的檔案與 .eslintrc.js 中會處理到的檔案不同，例如 tsconfig 只會處理 /src 內的檔案，但 .eslintrc.js 則是會處理所有專案中的 js 檔。

解決方式：

• 如果你「不要」 lint 這個檔案，則使用 .eslintignore 或 ESLint 中的 ignorePatterns 來忽略掉這隻檔案

• 如果你「要」 lint 這個檔案：

  • 但「不要」這個檔案出現和型別有關的錯誤（type-aware linting）：

    • 最簡單方式就是使用 ESLint overrides 的設定，只針對特定的檔案啟用這個規則：

    // .eslintrc.cjs
    module.exports = {
      // ... the rest of your config ...
      overrides: [
        {
          // specify the files that should be has type-aware linting:
          files: ['./src/**/*.{ts,tsx}'],
          parserOptions: {
            project: true,
            tsconfigRootDir: __dirname,
          },
          extends: ['plugin:@typescript-eslint/recommended-requiring-type-checking'],
        },
      ],
    };
    • @typescript-eslint 在 v6 之後可能會有更簡單的設定方式。

  • 同時「要」這個檔案有出現和型別有關的錯誤（type-aware linting）

    • 確定這個檔案有被列在 tsconfig 中的 include 內

    • 如果這個檔案想要被 lint 但並不歸在 tsconfig 要處理的範疇中（例如，tests/, 或 .eslintrc.js 等等），則建立另一個 tsconfig.eslint.json 的檔案，將這個檔案放在 include 中，參考這個 tsconfig.eslint.json 和 .eslintrc.js。（之所以這樣能解決，是因為 tsc 預設會吃 tsconfig.json，在沒有填 include 規則的情況下，預設會是 ["**/*"] 也就是專案中的所有檔案，因此就不會有想要 lint 但卻沒有被 tsc 包含到的情況。但實際上，我們並不是真的要 lint 所有檔案，這時候針對要 lint 的檔案在用 tsconfig.eslint.json 來做限制）。

搭配 husky 和 lint-staged

如果每次 git commit 前沒有先針對程式碼進行 ESLint 的檢查，這樣 linter 的功能等於只做了一半，因為開發者有可能完全不管 ESLint 的錯誤，還是把不符合 eslint 規範的程式碼推到 github 上。

husky

為了避免這個問題，我們可以使用 husky 這套工具，在建立 commit 時進行 ESLInt 的檢查。

# 第一次安裝 husky 才需要執行
$ npx husky-init && npm install

接著打開 .husky/pre-commit 這隻檔案，預設的情況下 husky 會在 git pre-commit 的階段執行 npm test，我們可以加上 eslint 的指令：

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx eslint . --ext .js,.ts.,.jsx,.tsx
npm test -- --watchAll=false

如此，husky 就會在 git 的 pre-commit hook 階段執行 eslint。

lint-staged

但如果每次建立 git commit 時都要對所有的檔案執行 eslint 的檢查的話非常沒有效率，有沒有可能只針對在 git staged 中的檔案執行 eslint 的檢查呢？

自動安裝與整合 husky

這時候我們可以再搭配 lint-staged 這套工具：

# 安裝 lint-staged 並自動與 husky 整合（專案中需要先安裝好 eslint 或 prettier）
npx mrm@2 lint-staged

手動安裝

如果沒辦法透過上述指令自動整合 lint-staged 的話（例如，create-react-app 的專案），則需要手動安裝和設定：

# 手動安裝
npm install --save-dev lint-staged

在 package.json 中，加上以下設定：

diff --git a/package.json b/package.json
index 4d92430..c347812 100644
--- a/package.json
+++ b/package.json
@@ -21,8 +21,14 @@
     "build": "react-scripts build",
     "test": "react-scripts test",
     "eject": "react-scripts eject",
+    "lint:staged": "lint-staged",
     "prepare": "husky install"
   },
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx}": [
+      "eslint --fix"
+    ]
+  },
 }

接著再 .husky/pre-commit 中，加上 npm run lint:staged 的指令，讓 husky 知道在 git commit 建立前要針對 staged 中的檔案執行 eslint 的檢查：

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npm run lint:staged

Writing Custom ESLint Rules

信息

AST Explorer

選擇對應的 Transform：

撰寫規則並檢視結果：

常見問題

xxx should be listed in the project's dependencies

throws spurious error on test files: @testing-library/react' should be listed in the project's dependencies, not devDependencies @ airbnb GitHub

問題說明：會出現這個問題是因為它認為在專案中有 import 到這個套件，但這個套件卻沒有被列在 package.json 中。

解決方式：針對 test files, configuration files

如果是測試的檔案（.test.js）出現這個錯誤，可以在 rules 的地方針對 'import/no-extraneous-dependencies' 的地方，使用 devDependencies 進行說明，讓它不會對測試檔案檢查此規則：

module.exports = {
  rules: {
    'import/no-extraneous-dependencies': [
      'warn',
      {
        devDependencies: [
          'test/**/*',
          'tests/**/*',
          '**/__tests__/**',
          '**/*.test.{js,jsx}',
          '**/*.test.jsx',

          /* 需要的時候也可以加上其他的檔案 */
          '**/*.stories.js',
          '**/*.stories.jsx',
          '**/.eslintrc.js', // eslint config
          '**/webpack.config.js', // webpack config
          '**/webpack.config.*.js', // webpack config
          '**/rollup.config.js', // rollup config
          '**/rollup.config.*.js', // rollup config
          '**/jest.config.js', // jest config
          '**/jest.setup.js', // jest setup
        ],
      },
    ],
  },
};

解決方式：針對 monorepos

如果是 monorepos 的話，因為並非所有的套件都會安裝在該 subpackages 內，則可以在 rules 中搭配 packageDir 使用：

// 列出所有 subpackages（有放 package.json 的 folder）
const packageDir = [
  path.join(__dirname, '.'),
  path.join(__dirname, 'packages/hooks'),
  path.join(__dirname, 'packages/core'),
  path.join(__dirname, 'packages/utils'),
];

module.exports = {
  rules: {
    'import/no-extraneous-dependencies': [
      'warn',
      {
        packageDir,
      },
    ],
  },
};

避免專案不認得 module.exports 等 node 語法

在 env 中加入 node：

module.exports = {
  env: {
    node: true,
  },
};

解決 Missing file extension "ts", "tsx" for

Typescript eslint - Missing file extension “ts” import/extensions @ stack overflow

會有這個問題時因為使用 TS 且搭配了 eslint-config-airbnb 的設定，需要修改 .eslintrc.js 中的 rules 和 settings：

const allExtensions = ['.ts', '.tsx', '.d.ts', '.js', '.jsx', '.json'];
module.exports = {
  rules: {
    // 解決 Missing file extension "ts" for ... (STEP 1)
    'import/extensions': [
      'error',
      'ignorePackages',
      {
        js: 'never',
        mjs: 'never',
        jsx: 'never',
        ts: 'never',
        tsx: 'never',
      },
    ],
  },
  settings: {
    // 解決 Missing file extension "ts" for ... (STEP 2)
    'import/extensions': allExtensions,
  },
};

解決 Parse errors in imported module

在 eslintrc 的 settings 中加上：

module.exports = {
  settings: {
    // 解決 Parse errors in imported module
    'import/parsers': {
      '@typescript-eslint/parser': ['.ts', '.tsx', '.d.ts'],
    },
  },
};

解決 Unable to resolve path to module (import/resolver)

Using eslint with typescript - Unable to resolve path to module @ stack overflow

當試著從 .js 中去 import .ts 或 .tsx 的檔案時，可能會出現這個錯誤。解決方式是在 settings 中增加以下設定：

const allExtensions = ['.ts', '.tsx', '.d.ts', '.js', '.jsx', '.json'];
module.exports = {
  settings: {
    // 解決 Unable to resolve path to module
    'import/resolver': {
      node: {
        extensions: allExtensions,
      },
    },
  },
};

如果是要使用 Absolute Imports / Import Aliases / Module Path Aliases 的話，可以參考 [[note] Absolute Imports and Module path aliases.md]([note] Absolute Imports and Module path aliases.md) 。

extends 和 plugin 的差別

• What's the difference between plugins and extends in eslint? And another good answer。

• ESLint extends vs plugins v2020：針對有寫好 config 的 plugin，可以不用在 plugins 中載入它，而是直接在 extends 中使用

plugin 會定義好一系列的規則但並沒有說明要如何使用這些規則，開發者必須根據自己的需要，在設定檔的 rules 欄位中選擇要使用哪些規則。也就是說，使用 plugin 並不會強制套用任何規則，你需要透過 rules 欄位自行設定當規則發生時，要被 ESLint 判斷成是 error、warning、還是可以不用理會。

當把套件放入 plugins 時，意思只是「啟用該套件」，但 ESLint 不會知道當規則發生時，要用 error、warning、或 off 來處理。

但 plugin 也可能會提供設定檔供你使用，如果有的話，你可以直接把它的設定檔放入 extends 欄位中，而不需要在 plugins 中載入。

extends 的對象則是「ESLint 設定檔」，可以透過 extends 的使用，直接載入別人寫好的設定檔到自己專案的 ESLint 設定檔中。

舉例來說：

• 因為 extends 中的 react/recommended 已經使用了 plugins: ["react"]，因此 react 這個 plugin 已將被啟用，我們就不需要自己在 plugins 欄位中啟用它：

"plugins": [],
"extends": [
  "eslint:recommended",
  "plugin:react/recommended"
]

備註

具體來說，plugins 提供你許多的規則，你可以自行選用，而 plugin 的作者也可能一併提供了他認為合理的設定檔讓你放在 extends 中使用，但這並不是強制的。

再以 eslint-plugin-prettier 為例，它有兩種不同的設定方式：

方式一：可以把 prettier 掛在 plugins 中再進行這定規則

{
  "plugins": ["prettier"],
  "rules": {
    "prettier/prettier": "error"
  }
}

方式二：也可以不掛入 plugins 中，直接套用 eslint-plugin-prettier 寫好的 config

{
  "extends": ["plugin:prettier/recommended"]
}

提示

之所以可以不用在 plugins 欄位套用 prettier 的原因在於，在 eslint-config-prettier 的設定檔中，就已經使用了 plugins:["prettier"] 來把 eslint-plugin-prettier 載入了。反之，若該 config 沒有直接在套件的 plugins 中載入（可以檢視該 config package 撰寫的 eslintrc 檔），則開發者就需要自己把它放到 plugins 中才會啟用。

使用 useEffect 時出現 consistent-return 的錯誤

當我們使用 useEffect 搭配 cleanup 時，有時候會這樣寫：

useEffect(() => {
  const modalRoot = document.getElementById('modal-root');

  if (!modalRoot) {
    return;
  }

  modalRoot.appendChild(el.current);

  // Arrow function expected no return consistent-return
  return () => {
    console.log('do cleanup here');
  };
}, []);

這時候會出現 Arrow function expected no return consistent-return 的錯誤。之所以會報錯，是因為 useEffect() 裡的 function 一個只用了 return，沒有給要 return 的 value；而最下方的 return 則有明確給了 return 的 value（這裡時 function）。

要滿足這個規則的話，要嘛就都 return 都要有 value，要嘛就都不要。

有解決這個問題可以 return undefined 即可：

  const Modal = ({ children }: ModalProps): ReactPortal => {
    const modalRoot = document.getElementById('modal-root');

    if (!modalRoot) {
-     return;
+     return undefined;
    }

    modalRoot.appendChild(el.current);

Integrate in VSCode

node version does not match that in terminal @ vscode-eslint

設定 ESLint 和 Prettier

1. install the ESLint extension & Prettier - Code formatter
2. Add the following settings in .vscode/settings.json

// .vscode/settings.json
{
  // ...
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "eslint.format.enable": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true
}

4. CMD + Shift + P, type and click "restart TS server"
5. CMD + Shift + P, type and click "restart ESLint server"

問題排查以及檢查執行 ESLint 的 Node 版本

keywords

• change the version of node that the eslint server is running on
• Enforcing node version on eslint server

在 VSCode 中執行 ESLint 的時候會在特定的 node version 底下：

這可能會導致某些不向下相容的 ESLint 套件產生錯誤，例如：

這時候需要指定 ESLint 在 VSCode 中執行的 runtime 版本，可以在 VSCode 的 settings.json 中，使用 eslint.runtime 的指令：

// settings.json
{
  "eslint.runtime": "/Users/user/.nvm/versions/node/v16.17.1/bin/node"

  // 也可以寫，會使用 VSCode 執行 node 的版本
  "eslint.runtime": "node"
}

設定好後，千萬要記得重新啟動 VSCode（Reload Window）：

危險

如果只是執行 "Restart ESLint Server" 可能會沒有效果。

接著回到 ESLint 的 Output 中，應該要能看到切換成對應的版本。

參考資料

[官方]

• ESLint
• ESLint Demo