[note] ESLint
keywords: CLI
, linted
- Configuring ESLint @ ESLint > UserGuide > Configuring
- Configuration Files @ ESLint > UserGuide > Configuration
- ESLint Demo
v9 有 breaking change
ESLint v9 後的 API 有 breaking change,使用 的是「flat configuration」,請在使用前先確認專案使用的 ESLint 版本。
Command Line Interface
$ npm init @eslint/config@latest
# npx eslint [options] [file|dir|glob]*
$ npx eslint yourfile.js
$ npx eslint file1.js file2.js
$ npx eslint "lib/**"
$ npx eslint # 等同於 npx eslint .
# Debug
npx eslint --print-config file.js # 使用時機:當你不確定為什麼 linting 沒有產生預期的結果
npx eslint --inspect-config # 使用時機:當你不確定某個檔案是否有套用到特定的 configuration object
ESLint Configuration
官方文件
// eslint.config.js
import exampleConfigs from 'eslint-config-example';
export default [
{
/**
* Globally Ignore these files
* 如果在 config object 中只使用 ignores 而沒有其他設定,
* 那麼這些 patterns 將會被當作全域的 ignores
*/
ignores: [
'dist',
'src/lib/api/schema.ts', // auto-generated by openapi-typescript
],
},
/**
* Cascading Configuration Objects
* 如果對於特定的檔案,有多個 config object 符合,
* 那麼這些 config object 會被合併,
* 當有衝突時後面的 object 會覆蓋前面的 object
*/
{
/**
* files 用來指定這個 config object 要套用的檔案 pattern。
* 如果這個 config object 沒有指定 files,
* 則這個 config object 的設定會作用在所有其他 config object 中有設定的 files 上,
* 類似 global configuration。
*/
files: ['**/*.js'],
linterOptions: {
reportUnusedDisableDirectives: 'error',
},
/**
* Configuring Shared Settings
* settings 只會作用在這個 config object 上
* 但這個 config object 中的所有 rules 都可以使用到這個 settings 的內容
*/
settings: {
react: { version: '18.3' },
},
},
{
/**
* js.configs.recommended 的 config object 只會作用在符合 files pattern 的檔案上
*/
...js.configs.recommended,
files: ['**/src/safe/*.js'],
},
/**
* 如果 import 的是 array of config object,
* 則可以用 array spread operator 把它展開
* */
...exampleConfigs,
];
debug 神器
在 CLI 中帶入參數 --inspect-config
會額外開啟 config inspector,可以用來檢視不同的檔案套用到了哪些 Rules,非常方便。
Legacy (v8 以前)
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]*
# 留意: --ext 主要是針對資料夾使用,表示只要 lint 這個資料夾內的特定副檔名,
# 但如果給的是檔案路徑,則 "ext" 這個參數會被忽略,一定會 lint 到這個檔案
$ eslint . --ext .jsx,.js,.ts,.tsx --cache --quiet --report-unused-disable-directives
# 只檢查和 develop branch 相比有變更的檔案(origin/develop...HEAD)
# 且不要檢查被刪除的檔案(--diff-filtered=d)
$ npx eslint -c .eslintrc $(git diff --name-only --diff-filter=d develop...HEAD)
# 檢視並複製當前套用到的 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 有兩種最主要的設定方式:
- 註解:在檔案中直接透過 JavaScript 的註解來進行設定
- 設定檔:為整個專案進行設定,一樣有兩種設定方式
- 使用 JavaScript、JSON 或 YAML 檔案來,它可以是
.eslintrc.*
的檔案 - 或在
package.json
中使用eslintConfig
這個欄位來進行設定
- 使用 JavaScript、JSON 或 YAML 檔案來,它可以是
透過 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 Modejsx
- 可以使用 JSX
// .eslintrc.json
{
"parserOptions": {
"ecmaVersion": 6,
"sourceType": "module",
"ecmaFeatures": {
"jsx": true,
"settings": {
// 這裡可以設定 react 的版本
"react": {
"version": "16.13.1"
}
}
}
}
}