Skip to content

@neosjs/eslint-config ​

NeosJS 的 ESLint 扁平配置(Flat Config)预设:一行配置即可获得合理的默认规则与最佳实践,自动修复代码格式(独立使用,不依赖 Prettier),并对 json、yaml、toml、markdown 等做语法检查。支持可选的 React、UnoCSS 集成,风格原则为最小化阅读、稳定的差异性、保持一致性(排序导入、单引号、末尾无分号,基于 ESLint Stylistic)。

前置要求

需要 ESLint v9.5.0+。默认遵守 .gitignore;Flat 配置中不再支持 .eslintignore,请使用 ignores 选项。

安装 ​

起始向导 ​

提供了一个命令行工具,帮助快速设置项目,或从旧配置一行命令迁移到扁平配置:

sh
npx @neosjs/eslint-config@latest

手动安装 ​

sh
pnpm i -D eslint @neosjs/eslint-config
sh
npm i -D eslint @neosjs/eslint-config
sh
yarn add -D eslint @neosjs/eslint-config

然后在项目根目录创建 eslint.config.mjs:

js
// eslint.config.mjs
import neosjs from '@neosjs/eslint-config'

export default neosjs()

在 package.json 中添加脚本:

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

快速上手 ​

自定义配置 ​

neosjs 工厂函数接受一个配置对象:

js
// eslint.config.js
import neosjs from '@neosjs/eslint-config'

export default neosjs({
  // 启用风格格式规则
  // stylistic: true,

  // 或自定义风格规则
  stylistic: {
    indent: 2, // 缩进
    semi: false, // 末尾分号
    quotes: 'single', // 引号:'single' | 'double'
    commaDangle: 'never' // 末尾逗号:'never' | 'always' | 'always-multiline' | 'only-multiline'
  },

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

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

  // Flat 配置中不再支持 .eslintignore,请使用 ignores
  ignores: [
    // ...globs
  ]
})

也接受任意数量的自定义配置覆盖,逐项传入:

js
// eslint.config.js
import neosjs from '@neosjs/eslint-config'

export default neosjs(
  {
    // neosjs 预设的配置
  },
  // 可以有多个配置
  {
    files: ['**/*.ts'],
    rules: {}
  },
  {
    rules: {}
  }
)

React / UnoCSS ​

React 与 UnoCSS 支持需显式开启:

js
// eslint.config.js
import neosjs from '@neosjs/eslint-config'

export default neosjs({
  react: true,
  unocss: true
})

运行 npx eslint 会提示安装所需依赖,也可以手动安装:

sh
npm i -D @unocss/eslint-plugin                              # UnoCSS
npm i -D @eslint-react/eslint-plugin eslint-plugin-react-hooks eslint-plugin-react-refresh  # React

规则覆盖 ​

某些规则仅在特定文件中启用(例如 ts/* 规则只在 .ts 文件、vue/* 规则只在 .vue 文件),覆盖时需指定文件 glob:

js
// eslint.config.js
import neosjs from '@neosjs/eslint-config'

export default neosjs(
  { vue: true, typescript: true },
  {
    // 记得指定 files,否则可能导致 vue 插件处理非 vue 文件
    files: ['**/*.vue'],
    rules: {
      'vue/operator-linebreak': ['error', 'before']
    }
  },
  {
    // 没有 files,则是应用于所有文件的一般规则
    rules: {
      'style/semi': ['error', 'never']
    }
  }
)

vue / typescript 等集成还提供 overrides 选项,按集成聚焦覆盖:

js
// eslint.config.js
import neosjs from '@neosjs/eslint-config'

export default neosjs({
  vue: {
    overrides: {
      'vue/operator-linebreak': ['error', 'before']
    }
  },
  typescript: {
    overrides: {
      'ts/consistent-type-definitions': ['error', 'interface']
    }
  }
})

VS Code 支持(保存时自动修复) ​

  1. 安装 VS Code ESLint 扩展;
  2. 在 .vscode/settings.json 中添加:
jsonc
{
  // 启用 ESLint flat config 支持
  "eslint.experimental.useFlatConfig": true,

  // 禁用默认的格式化程序,改用 ESLint 进行格式化
  "prettier.enable": false,
  "editor.formatOnSave": false,

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

  // 在 IDE 中隐藏样式规则的提示,但仍自动修复它们
  "eslint.rules.customizations": [
    { "rule": "style/*", "severity": "off" },
    { "rule": "format/*", "severity": "off" },
    { "rule": "*-indent", "severity": "off" },
    { "rule": "*-spacing", "severity": "off" },
    { "rule": "*-spaces", "severity": "off" },
    { "rule": "*-order", "severity": "off" },
    { "rule": "*-dangle", "severity": "off" },
    { "rule": "*-newline", "severity": "off" },
    { "rule": "*quotes", "severity": "off" },
    { "rule": "*semi", "severity": "off" }
  ],

  // 为所有支持的语言启用 ESLint
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "vue",
    "html",
    "markdown",
    "json",
    "jsonc",
    "yaml",
    "toml"
  ]
}

其他 ​

Lint Staged ​

在每次提交前执行 lint 并自动修复,在 package.json 中添加:

json
{
  "simple-git-hooks": {
    "pre-commit": "pnpm lint-staged"
  },
  "lint-staged": {
    "*": "eslint --fix"
  }
}

然后运行:

sh
npm i -D lint-staged simple-git-hooks
npx simple-git-hooks

查看启用的规则 ​

使用可视化工具查看项目中启用了哪些规则、应用到哪些文件:在包含 eslint.config.js 的项目根目录运行:

sh
npx eslint-flat-config-viewer