@neosjs/eslint-config/README.md

Neosjs's ESLint config

# @neosjs/eslint-config

![NPM Version][npm-version-image] ![Npm Week Downloads][npm-downloads-image-week] ![Npm Month Downloads][npm-downloads-image-month] ![Node Version][node-current] ![License][license-image] ![ESlint Config][eslint-config]

- 自动修复格式（旨在独立使用 **不包括** Prettier）
- 合理的默认设置，最佳实践，只需一行配置
- 对json，yaml，toml，markdown等进行语法检查
- [ESLint Flat配置](https://eslint.org/docs/latest/use/configure/configuration-files-new)，轻松组合！
- 可选的[React](#react),[UnoCSS](#unocss)支持。
- 可选的格式化代码支持CSS，HTML等。
- **风格原则**: 最小化阅读，稳定的差异性，保持一致性
  - 排序导入文件
  - 单引号，末尾无分号
  - 使用 [ESLint Stylistic](https://github.com/eslint-stylistic/eslint-stylistic)
- 默认情况下遵守 `.gitignore`
- 需要 ESLint v9.5.0+

## 使用方法

### 起始向导

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

```bash
npx @neosjs/eslint-config@latest
```

### 手动安装

如果您更喜欢手动设置：

```bash
pnpm i -D eslint @neosjs/eslint-config
```

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

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

export default neosjs()
```

### 在 package.json 中添加脚本

For example:

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

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

## VS Code支持（自动修复）

为了在Visual Studio Code中实现保存时自动修复代码的功能，您需要安装ESLint扩展并配置相应的设置。以下是详细的步骤和说明：

1. 安装 [VS Code ESLint扩展](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-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"
  ]
}
```

## 自定义

支持[ESLint Flat 配置](https://eslint.org/docs/latest/use/configure/configuration-files-new)。它提供了更好的组织和组合。

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

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

export default 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
  ]
})
```

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

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

export default neosjs(
  {
    // 为neosjs的配置配置
  },

  // 可以有多个配置
  {
    files: ['**/*.ts'],
    rules: {},
  },
  {
    rules: {},
  },
)
```

### Vue

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

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

export default neosjs({
  vue: true
})
```

### UnoCSS

要启用UnoCSS支持，您需要显式地打开它:

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

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

运行 `npx eslint` 会提示你安装所需的依赖项，你也可以手动安装它们:

```bash
npm i -D @unocss/eslint-plugin
```

### React

To enable React support, you need to explicitly turn it on:

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

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

运行 `npx eslint` 会提示你安装所需的依赖项，你也可以手动安装它们:

```bash
npm i -D @eslint-react/eslint-plugin eslint-plugin-react-hooks eslint-plugin-react-refresh
```

### 规则覆盖

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

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

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

我们还提供了一个 `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'],
    },
  }
})
```

### Lint Staged

如果您想在每次提交之前应用lint和自动修复，可以将以下内容添加到您的 `package.json` 中：

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

然后运行：

```bash
npm i -D lint-staged simple-git-hooks

// to active the hooks
npx simple-git-hooks
```

## 查看启用的规则

一个可视化工具，帮助您查看项目中启用了哪些规则，并将它们应用于哪些文件，[@eslint/config-inspector](https://github.com/eslint/config-inspector)

前往包含 `eslint.config.js` 的项目根目录，并运行：

```bash
npx eslint-flat-config-viewer
```

## License

[MIT](./LICENSE) License © 2021-PRESENT [NeosJS](https://docs.neosjs.com/)

[npm-version-image]: https://img.shields.io/npm/v/@neosjs/eslint-config?style=flat&colorA=2d333b&colorB=1fa669
[npm-downloads-image-week]: https://img.shields.io/npm/dw/@neosjs/eslint-config?style=flatt&colorA=2d333b&colorB=1fa669
[npm-downloads-image-month]: https://img.shields.io/npm/dm/@neosjs/eslint-config?style=flat&colorA=2d333b&colorB=1fa669
[license-image]: https://img.shields.io/npm/l/@neosjs/eslint-config?style=flat&colorA=2d333b&colorB=1fa669
[eslint-config]: https://img.shields.io/badge/NeosJS-eslint--config-1fa669?style=flat&colorA=2d333b&colorB=1fa669
[node-current]: https://img.shields.io/node/v/@neosjs/eslint-config?style=flat&colorA=2d333b&colorB=1fa669