@kirklin/eslint-config

English | 简体中文

Features

“双引号”，必须有分号;
自动修复格式（旨在独立使用 不包括 Prettier）
排序导入项，悬挂逗号
合理的默认设置，最佳实践，只需一行配置
设计用于与TypeScript，JSX，Vue无缝配合
对json，yaml，toml，markdown等进行语法检查
有主见，但可非常定制化
ESLint Flat配置，轻松组合！
使用ESLint Stylistic
默认情况下遵守.gitignore
可选的React, Svelte, UnoCSS, Astro, Solid支持
可选的格式化程序支持CSS，HTML，XML等。
样式原则：最小化阅读，稳定的差异性，保持一致性

Important

从v1.0.0开始，该配置已重写为新的 ESLint Flat配置, 请查看发布说明以获取更多详细信息。

自 v2.7.0 起，需要 ESLint v9.5.0+。

使用方法

起始向导

我们提供了一个命令行工具，帮助您快速设置项目，或者通过一个命令从旧的配置迁移到新的平面配置。

pnpm dlx @kirklin/eslint-config@latest

手动安装

如果您更喜欢手动设置：

pnpm i -D eslint @kirklin/eslint-config

然后在您的项目根目录下创建 eslint.config.mjs 文件：

// eslint.config.mjs
import kirklin from "@kirklin/eslint-config";

export default kirklin();

结合旧版配置:

如果您仍然使用旧版eslintrc的一些配置，您可以使用@eslint/eslintrc将它们转换为flat config

import { FlatCompat } from "@eslint/eslintrc";
// eslint.config.mjs
import kirklin from "@kirklin/eslint-config";

const compat = new FlatCompat();

export default kirklin(
  {
    ignores: [],
  },

  // Legacy config
  ...compat.config({
    extends: [
      "eslint:recommended",
      // Other extends...
    ],
  })

  // Other flat configs...
);

请注意，在Flat配置中不再支持 .eslintignore，请查看自定义以获取更多详细信息。

在 package.json 中添加脚本

For example:

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix"
  }
}

IDE 支持（保存时自动修复）

🟦 VS Code 支持

安装 VS Code ESLint 插件

在 .vscode/settings.json 中添加以下设置：

{
  // 禁用默认格式化器，使用 eslint 代替
  "prettier.enable": false,
  "editor.formatOnSave": false,

  // 自动修复
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit",
    "source.organizeImports": "never"
  },

  // 在IDE中静默样式规则，但仍然自动修复
  "eslint.rules.customizations": [
    { "rule": "style/*", "severity": "off", "fixable": true },
    { "rule": "format/*", "severity": "off", "fixable": true },
    { "rule": "*-indent", "severity": "off", "fixable": true },
    { "rule": "*-spacing", "severity": "off", "fixable": true },
    { "rule": "*-spaces", "severity": "off", "fixable": true },
    { "rule": "*-order", "severity": "off", "fixable": true },
    { "rule": "*-dangle", "severity": "off", "fixable": true },
    { "rule": "*-newline", "severity": "off", "fixable": true },
    { "rule": "*quotes", "severity": "off", "fixable": true },
    { "rule": "*semi", "severity": "off", "fixable": true }
  ],

  // 为所有支持的语言启用 eslint
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "vue",
    "html",
    "markdown",
    "json",
    "jsonc",
    "yaml",
    "toml",
    "xml",
    "gql",
    "graphql",
    "astro",
    "svelte",
    "css",
    "less",
    "scss",
    "pcss",
    "postcss"
  ]
}

🟩 Neovim 支持

更新你的配置，使用以下内容：

local customizations = {
  { rule = 'style/*', severity = 'off', fixable = true },
  { rule = 'format/*', severity = 'off', fixable = true },
  { rule = '*-indent', severity = 'off', fixable = true },
  { rule = '*-spacing', severity = 'off', fixable = true },
  { rule = '*-spaces', severity = 'off', fixable = true },
  { rule = '*-order', severity = 'off', fixable = true },
  { rule = '*-dangle', severity = 'off', fixable = true },
  { rule = '*-newline', severity = 'off', fixable = true },
  { rule = '*quotes', severity = 'off', fixable = true },
  { rule = '*semi', severity = 'off', fixable = true },
}

local lspconfig = require('lspconfig')
-- 为所有支持的语言启用 eslint
lspconfig.eslint.setup(
  {
    filetypes = {
      "javascript",
      "javascriptreact",
      "javascript.jsx",
      "typescript",
      "typescriptreact",
      "typescript.tsx",
      "vue",
      "html",
      "markdown",
      "json",
      "jsonc",
      "yaml",
      "toml",
      "xml",
      "gql",
      "graphql",
      "astro",
      "svelte",
      "css",
      "less",
      "scss",
      "pcss",
      "postcss"
    },
    settings = {
      -- 在IDE中静默样式规则，但仍然自动修复
      rulesCustomizations = customizations,
    },
  }
)

Neovim 保存时格式化

在 Neovim 中实现保存时格式化有几种方法：

nvim-lspconfig 预定义了 EslintFixAll 命令，你可以创建一个 autocmd，在保存文件后调用该命令。

lspconfig.eslint.setup({
  --- ...
  on_attach = function(client, bufnr)
    vim.api.nvim_create_autocmd("BufWritePre", {
      buffer = bufnr,
      command = "EslintFixAll",
    })
  end,
})

使用 conform.nvim。
使用 none-ls。
使用 nvim-lint。

自定义

从v1.0开始，我们迁移到了ESLint Flat 配置。它提供了更好的组织和组合。

通常，您只需要导入 kirklin 预设：

// eslint.config.js
import kirklin from "@kirklin/eslint-config";

export default kirklin();

就是这样！或者您还可以单独配置每个集成，例如：

// eslint.config.js
import kirklin from "@kirklin/eslint-config";

export default kirklin({
  // 项目类型。'lib' 表示库，默认是 'app'
  type: "lib",

  // 启用风格格式规则
  // stylistic: true,

  // 或自定义风格规则
  stylistic: {
    indent: 2, // 4或'tab'
    quotes: "double", // 或'single'
  },

  // TypeScript和Vue会自动检测，您也可以显式启用它们：
  typescript: true,
  vue: true,

  // 禁用jsonc和yaml支持
  jsonc: false,
  yaml: false,

  // 在Flat配置中不再支持`.eslintignore`，请使用`ignores`代替
  ignores: [
    "**/fixtures",
    // ...globs
  ]
});

kirklin 工厂函数还接受任意数量的自定义配置覆盖：

// eslint.config.js
import kirklin from "@kirklin/eslint-config";

export default kirklin(
  {
    // Configures for kirklin's config
  },

  // From the second arguments they are ESLint Flat Configs
  // you can have multiple configs
  {
    files: ["**/*.ts"],
    rules: {},
  },
  {
    rules: {},
  },
);

更高级的情况下，您还可以导入细粒度的配置并根据需要组合它们：

高级示例

我们不建议在一般用途中使用这种样式，因为在配置之间可能存在共享选项，可能需要额外的注意以使它们一致。

// eslint.config.js
import {
  combine,
  comments,
  ignores,
  imports,
  javascript,
  jsdoc,
  jsonc,
  markdown,
  node,
  sortPackageJson,
  sortTsconfig,
  stylistic,
  toml,
  typescript,
  unicorn,
  vue,
  yaml,
} from "@kirklin/eslint-config";

export default combine(
  ignores(),
  javascript(/* Options */),
  comments(),
  node(),
  jsdoc(),
  imports(),
  unicorn(),
  typescript(/* Options */),
  stylistic(),
  vue(),
  jsonc(),
  yaml(),
  toml(),
  markdown(),
);

查看configs和factory以获取更多详细信息。

感谢 sxzz/eslint-config 提供灵感和参考。

插件重命名

由于Flat配置要求我们明确提供插件名称（而不是从npm包名称强制性约定），我们已经重命名了一些插件，以使整体范围更一致且更容易编写。

New Prefix	Original Prefix	Source Plugin
`import/*`	`import-x/*`	eslint-plugin-import-x
`node/*`	`n/*`	eslint-plugin-n
`yaml/*`	`yml/*`	eslint-plugin-yml
`ts/*`	`@typescript-eslint/*`	@typescript-eslint/eslint-plugin
`style/*`	`@stylistic/*`	@stylistic/eslint-plugin
`test/*`	`vitest/*`	@vitest/eslint-plugin
`test/*`	`no-only-tests/*`	eslint-plugin-no-only-tests

当您想要覆盖规则或在内联中禁用它们时，您需要更新新前缀：

-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+// eslint-disable-next-line ts/consistent-type-definitions
type foo = { bar: 2 }

Note

关于插件重命名 - 实际上这是一个相当危险的举动，可能会导致潜在的命名冲突，如这里和这里所指出的。由于这个配置非常个人化和主观化，我雄心勃勃地将这个配置定位为每个项目唯一的**"顶层"**配置，这可能会改变规则命名的偏好。

这个配置更关心面向用户的体验，试图简化实现细节。例如，用户可以继续使用语义化的 import/order，而无需知道底层插件已经迁移到 eslint-plugin-i 然后再到 eslint-plugin-import-x。用户也不被迫在中途迁移到隐式的 i/order，仅仅因为我们将实现换成了一个分支。

话虽如此，这可能仍然不是一个好主意。如果你正在维护自己的 eslint 配置，你可能不想这样做。

如果你想将这个配置与其他配置预设组合使用，但遇到了命名冲突，请随时提出问题。我很乐意找出一种方法让它们协同工作。但目前我没有计划撤销重命名。

从 v2.3.0 版本开始，这个预设将自动重命名插件，也适用于您的自定义配置。您可以使用原始前缀直接覆盖规则。

恢复原始前缀

如果你确实想使用原始前缀，可以通过以下方式还原插件重命名：

import kirklin from "@kirklin/eslint-config";

export default kirklin()
  .renamePlugins({
    ts: "@typescript-eslint",
    yaml: "yml",
    node: "n"
    // ...
  });

规则覆盖

某些规则仅在特定文件中启用，例如， ts/* 规则仅在 .ts 文件中启用， vue/* 规则仅在 .vue 文件中启用。如果要覆盖规则，需要指定文件扩展名：

// eslint.config.js
import kirklin from "@kirklin/eslint-config";

export default kirklin(
  {
    vue: true,
    typescript: true
  },
  {
    // 记得在这里指定文件glob，否则可能会导致vue插件处理非vue文件
    files: ["**/*.vue"],
    rules: {
      "vue/operator-linebreak": ["error", "before"],
    },
  },
  {
    // 没有`files`，它们是所有文件的一般规则
    rules: {
      "style/semi": ["error", "never"],
    },
  }
);

我们还提供了一个 overrides 选项，以使其更容易：

// eslint.config.js
import kirklin from "@kirklin/eslint-config";

export default kirklin({
  vue: {
    overrides: {
      "vue/operator-linebreak": ["error", "before"],
    },
  },
  typescript: {
    overrides: {
      "ts/consistent-type-definitions": ["error", "interface"],
    },
  },
  yaml: {
    overrides: {
      // ...
    },
  },
});

配置组合器

从 v2.3.0 版本开始，工厂函数 kirklin() 返回了一个来自 eslint-flat-config-utils 的 FlatConfigComposer 对象。您可以链式调用方法，以更加灵活地组合配置。

// eslint.config.js
import kirklin from "@kirklin/eslint-config";

export default kirklin()
  .prepend(
    // 主配置之前的一些配置
  )
  // 覆盖任何命名配置
  .override(
    "kirklin/imports",
    {
      rules: {
        "import/order": ["error", { "newlines-between": "always" }],
      }
    }
  )
  // 重命名插件前缀
  .renamePlugins({
    "old-prefix": "new-prefix",
    // ...
  });
// ...

这段代码展示了如何使用 FlatConfigComposer 来更加精细地控制您的 ESLint 配置。通过 prepend 方法，您可以在主配置之前添加一些配置。override 方法允许您覆盖任何命名配置的规则。最后，renamePlugins 方法可以用于重命名插件前缀，这在处理潜在的命名冲突时非常有用。

Vue

对于Vue框架的支持，是通过检查项目中是否安装了vue来自动检测的。您也可以明确地启用或禁用它：

// eslint.config.js
import kirklin from "@kirklin/eslint-config";

export default kirklin({
  vue: true
});

Vue 2

对于Vue 2的有限支持（因为它已经达到了生命周期结束），如果您仍在使用Vue 2，可以通过设置vueVersion为2来手动配置它：

// eslint.config.js
import kirklin from "@kirklin/eslint-config";

export default kirklin({
  vue: {
    vueVersion: 2
  },
});

由于Vue 2目前已经进入维护模式，我们只接受针对Vue 2的错误修复。当eslint-plugin-vue停止支持Vue 2时，我们可能会在未来移除对Vue 2的支持。如果可能的话，我们推荐您升级到Vue 3。

可选配置

我们为特定的使用场景提供了一些可选的配置，默认情况下不包含它们的依赖。这些可选配置允许您根据项目的具体需求来选择性地引入和使用，从而避免不必要的依赖引入和性能开销。您可以根据项目需要，选择启用或禁用这些可选配置。如果您想了解更多关于如何使用这些可选配置的信息，可以查阅相关文档或在社区中寻求帮助。