@bassist/eslint-config

English | 简体中文

一款现代化的扁平 ESLint 配置，适用于 ESLint V9 ，由 @chengpeiquan 精心打造。

⚡ 使用方法

使用此 ESLint 配置仅需三步：

1. 安装依赖（参考：🚀 安装）
2. 添加 ESLint 配置文件（参考：📂 配置文件）
3. 在 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 支持
# 才可以使用 `eslint.config.ts` 作为配置文件
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,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "always",
    "source.fixAll.prettier": "always"
  },
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "eslint.useFlatConfig": true,
  "eslint.format.enable": true,
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],
  "prettier.configPath": "./.prettierrc.js"
}

关于 prettier.configPath 请查看 格式化工具 部分。

📘 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`，手动合并后再传入。
   *
   * 如果传入空对象 `{}`，则会使用默认设置。
   *
   * @see https://github.com/francoismassart/eslint-plugin-tailwindcss/tree/v3.18.2
   */
  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！

语言支持

• JavaScript
• TypeScript
• JSX
• Markdown

框架支持

• Next.js
• React
• Vue (v2 and v3)

格式化工具

格式化规则默认启用，不会单独导出。如需自定义配置，请通过 defineFlatConfig API 的 options 传入。

• Prettier :
  • 默认会读取 .prettierrc 和 .prettierignore 的内容，并添加到 ESLint 规则中。
  • 如果预期的配置文件不存在，则会使用 内置的 Prettier 规则作为兜底规则。
  • 非以上配置文件并且不喜欢默认规则时，可以通过 defineFlatConfig 的 options.prettierRules 将完整配置传递进来优先作为 ESLint 规则使用
• Tailwind CSS :
  • 默认会将 tailwind.config.js 作为 Tailwind CSS 配置文件传入。
  • 非默认文件或者需要更改规则，可通过 options.tailwindcssSettings 传递

其它

• Node.js
• Imports
• Regexp
• Unicorn

📚 迁移指南

• 扁平化配置（Flat Configs）不支持 ESLint 8.x 以下的版本。
• --ext CLI 选项已被移除 (#16991) 。

📝 发布日志

详细更新内容请参考 CHANGELOG 。

📜 License

MIT License © 2023-PRESENT chengpeiquan