适用于 ESLint V9 的现代化扁平化配置
ESLint v9.0.0 是 ESLint 的一个主要版本,它有几个重大变化,其中最大的变化是其配置文件和插件生态系统的使用,可以通过官方网站的 迁移到 v9.x 文档了解如何迁移。
这里有一个关于 ESLint V9 的扁平化配置的 npm 包,内置了一些个人常用的 ESLint 配置,这也是我在 GitHub 上发布的一个开源项目。如果它对您有帮助,请 给它一个 Star !
一款现代化的扁平 ESLint 配置,适用于 ESLint V9 ,由 @chengpeiquan 精心打造。
⚡ 使用方法
使用此 ESLint 配置仅需三步:
- 安装依赖(参考:🚀 安装)
- 添加 ESLint 配置文件(参考:📂 配置文件)
- 在 VS Code 的
settings.json
启用自动 Lint(参考:🛠 VS Code 配置)
这个快速指南可以作为入门辅助,避免遗漏关键步骤 🚀 。
🚀 安装
使用常用的包管理器安装该包:
npm install -D eslint @bassist/eslint-config
注意: 需要 ESLint 版本 >= 9.0.0
,以及 TypeScript 版本 >= 5.0.0
。
如果使用的是 pnpm
,建议在项目根目录添加 .npmrc
文件,并包含以下配置,以更顺利地处理 peer 依赖:
shamefully-hoist=true
auto-install-peers=true
如果仍在使用 ESLint v8,请参考旧版(已不再维护)包:@bassist/eslint。
📂 配置文件
在项目根目录创建 eslint.config.js
文件:
// eslint.config.js
import { imports, typescript } from '@bassist/eslint-config'
// 导出一个包含多个配置对象的数组
export default [...imports, ...typescript]
然后在 package.json
中添加 "type": "module" :
{
"type": "module",
"scripts": {
"lint": "eslint src",
"lint:inspector": "npx @eslint/config-inspector"
}
}
运行 npm run lint
以检查代码,或运行 npm run lint:inspector
在 http://localhost:7777
查看可视化的 ESLint 配置。
对于 TypeScript 配置文件(例如
eslint.config.ts
),需要 额外的设置 。
# 为 Node.js 提供运行时 TypeScript 和 ESM 支持
npm install -D jiti
✅ 类型安全的配置
为了增强类型安全性,可以使用 defineFlatConfig
:
// @ts-check
import { defineFlatConfig, imports, vue } from '@bassist/eslint-config'
export default defineFlatConfig([
...imports,
...vue,
// 添加更多自定义配置
{
// 为每个配置提供名称,以便在运行 `npm run lint:inspector` 时,
// 可以在可视化工具中清晰展示
name: 'my-custom-rule/vue',
rules: {
// 例如:默认情况下,该规则是 `off`
'vue/component-tags-order': 'error',
},
ignores: ['examples'],
},
])
🛠 VS Code 配置
在 VS Code 工作区的 settings.json
添加以下配置,以启用自动 Lint 修复:
{
"editor.formatOnSave": true,
"eslint.useFlatConfig": true,
"editor.codeActionsOnSave": {
"source.fixAll.eslint": "always",
"source.fixAll.prettier": "always"
}
}
📘 API 参考
defineFlatConfig
定义 ESLint 配置,可选支持 Prettier 和 Tailwind CSS。
API 类型声明:
/**
* 定义 ESLint 配置,可选支持 Prettier 集成。
*
* @param configs 基础 ESLint 配置数组。
* @param options - 配置选项。
*
* @returns 最终的 ESLint 配置数组。
*/
declare const defineFlatConfig: (
configs: FlatESLintConfig[],
options?: DefineFlatConfigOptions,
) => FlatESLintConfig[]
选项类型声明:
interface DefineFlatConfigOptions {
/**
* 指定用于加载 `.prettierrc` 配置的工作目录。
*
* 配置文件应为 JSON 格式。
*
* @default process.cwd()
*/
cwd?: string
/**
* 如果 `prettierEnabled` 设为 `false`,则所有与 Prettier 相关的规则和配置都将被忽略,
* 即使提供了 `prettierRules` 也不会生效。
*
* @default true
*/
prettierEnabled?: boolean
/**
* 默认情况下,会从当前工作目录读取 `.prettierrc`,并且 `.prettierrc` 文件必须是 JSON 格式。
*
* 如果配置文件不是 JSON 格式,或者使用了不同的文件名,可以将其转换为 JSON 规则后传入。
*
* 读取自定义配置后,会与默认的 ESLint 规则合并。
*
* @see https://prettier.io/docs/configuration.html
*/
prettierRules?: PartialPrettierExtendedOptions
/**
* Tailwind CSS 规则默认启用。如果它们影响了项目,可以通过该选项禁用。
*
* @default true
*/
tailwindcssEnabled?: boolean
/**
* 如果需要覆盖 Tailwind CSS 配置,可以传入相应的选项。
*
* 如果想要合并配置,可以导入 `defaultTailwindcssSettings`,手动合并后再传入。
*
* 如果传入空对象 `{}`,则会使用默认设置。
*/
tailwindcssSettings?: TailwindcssSettings
}
createGetConfigNameFactory
createGetConfigNameFactory
是一个灵活的工具函数,用于生成 ESLint 配置命名工具。它可以快速拼接配置名称,确保命名空间一致,并便于组织和管理复杂的规则集。
API 类型声明:
/**
* 一个灵活的工具函数,用于生成 ESLint 配置命名工具。
* 它可以快速拼接配置名称,确保命名空间一致,并便于组织和管理复杂的规则集。
*
* @param prefix - 表示配置名称前缀的字符串。
* @returns 一个函数,该函数会将提供的名称片段与指定的前缀拼接在一起。
*/
declare const createGetConfigNameFactory: (
prefix: string,
) => (...names: string[]) => string
使用示例:
import {
createGetConfigNameFactory,
defineFlatConfig,
} from '@bassist/eslint-config'
const getConfigName = createGetConfigNameFactory('my-prefix')
export default defineFlatConfig([
{
name: getConfigName('ignore'), // --> `my-prefix/ignore`
ignores: ['**/dist/**', '**/.build/**', '**/CHANGELOG.md'],
},
])
为什么要使用它?
- 一致性:强制执行清晰统一的配置命名模式。
- 灵活性:允许为不同项目或范围自定义前缀。
- 简化管理:便于组织和浏览大型 ESLint 配置。
这个工具在构建可复用的 ESLint 配置或维护复杂项目的规则集时尤其有用。
📦 导出的配置
这些是一些常用的配置,如果有额外需求,欢迎提交 PR!
语言支持
框架支持
格式化工具
格式化规则默认启用,不会单独导出。如需自定义配置,请通过 defineFlatConfig API 的 options
传入。
- Prettier : 默认会读取
.prettierrc
和.prettierignore
的内容,并添加到 ESLint 规则中。 - Tailwind CSS : 默认会将
tailwind.config.js
作为 Tailwind CSS 配置文件传入。
其它
📚 迁移指南
- 扁平化配置(Flat Configs)不支持 ESLint 8.x 以下的版本。
--ext
CLI 选项已被移除 (#16991) 。
📝 发布日志
详细更新内容请参考 CHANGELOG 。