@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-configsh
npm i -D eslint @neosjs/eslint-configsh
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 支持(保存时自动修复)
- 安装 VS Code ESLint 扩展;
- 在
.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