@refinist/eslint-config

为 JavaScript、TypeScript、Vue、React 和 Prettier 提供的 ESLint 配置预设

English Documentation | 中文文档

特性

• 🎨 使用 Prettier 格式化
• ⚡ 专为 Vue3 & TypeScript 或 React & TypeScript 设计
• 📋 ESLint 扁平配置
• 🚫 自动忽略常见文件如 node_modules、dist 和 .gitignore 中的文件
• 🎯 最佳实践，只需一行配置
• 💬 内置 @stylistic/eslint-plugin 的 @stylistic/spaced-comment 规则，在注释后添加空格（适合强迫症😬）
• 内置 Tailwindcss 3/4 自动格式化/纠错插件支持，相关文档，使用方法见这里
• 💡 通过 typescript.tsconfigPath 配置启用 type-aware，TypeScript 和 React 均可受益，相关资料
• 🔀 排序相关，排序 imports, 排序 package.json，pnpm-workspace.yaml，tsconfig.json...
• 💯 只为追求更高的代码质量，仅此而已
• TODO:添加更多语言支持

安装

使用 pnpm、yarn、npm 或 bun

# 使用 pnpm
pnpm add -D @refinist/eslint-config

# 使用 yarn
yarn add -D @refinist/eslint-config

# 使用 npm
npm i -D @refinist/eslint-config

# 使用 bun
bun add -D @refinist/eslint-config

[!WARNING] 如果你使用 react，请额外安装这三个包 pnpm add -D @eslint-react/eslint-plugin@^1.52.3 eslint-plugin-react-hooks@^5.2.0 eslint-plugin-react-refresh@^0.4.20，然后手动引入 react eslint 包 import { react } from '@refinist/eslint-config/react' 配置如下👇

// eslint.config.ts
import { refinist } from '@refinist/eslint-config';
import { react } from '@refinist/eslint-config/react';
export default refinist({}, react());

启用 type-aware

配置 typescript.tsconfigPath 后，TypeScript 和 React 都会自动启用 type-aware 规则：

// eslint.config.ts
import { refinist } from '@refinist/eslint-config';
import { react } from '@refinist/eslint-config/react';
export default refinist(
  {
    typescript: {
      tsconfigPath: 'tsconfig.json'
    }
  },
  react()
);

需要 Node.js >= 20.0.0 和 ESLint >= 9.5.0。

使用方法

// eslint.config.ts
import { refinist } from '@refinist/eslint-config';
export default refinist();

// eslint.config.ts
import { refinist } from '@refinist/eslint-config';
export default refinist({
  vue: true, // 自动检测
  prettier: true // 默认为 true
});

规则覆盖

// eslint.config.ts
import { refinist } from '@refinist/eslint-config';
export default refinist(
  {},

  // 从第二个参数开始，它们是 ESLint 扁平配置
  // 你可以有多个配置
  {
    files: ['**/*.ts'],
    rules: {}
  },
  {
    rules: {}
  }
);

使用系统的 glob

// eslint.config.ts
import { refinist, GLOB_VUE } from '@refinist/eslint-config';
export default refinist(
  {},

  {
    files: [GLOB_VUE], // GLOB_VUE 是 '**/*.vue'
    rules: {
      'vue/block-order': 'off'
    }
  }
);

使用 Tailwindcss ESLint 插件

[!WARNING] 如果你使用了 @refinist/prettier-config/with-tailwindcss，请忽略下面的配置。因为它们的功能类似，你也可以对比它们的区别，这取决于你

// eslint.config.ts
import { refinist } from '@refinist/eslint-config';
export default refinist({
  // ...
  tailwindcss: {
    // 配置参考 https://github.com/schoero/eslint-plugin-better-tailwindcss/blob/main/docs/settings/settings.md#settings
    entryPoint: 'src/global.css'
  }
});

规则覆盖

// eslint.config.ts
import { refinist, GLOB_TAILWINDCSS } from '@refinist/eslint-config';
export default refinist(
  {},

  {
    files: GLOB_TAILWINDCSS,
    // https://github.com/schoero/eslint-plugin-better-tailwindcss/tree/main/docs/rules
    rules: {
      'better-tailwindcss/no-unregistered-classes': [
        'warn',
        { detectComponentClasses: true }
      ]
    }
  }
);

### 🔗 Prettier 配置

与 [@refinist/prettier-config](https://github.com/refinist/prettier-config) 结合使用

#### 安装

```bash
# 使用 pnpm
pnpm add -D @refinist/prettier-config

# 使用 yarn
yarn add -D @refinist/prettier-config

# 使用 npm
npm i -D @refinist/prettier-config

# 使用 bun
bun add -D @refinist/prettier-config

package.json 配置（推荐）

// package.json
{
  "prettier": "@refinist/prettier-config"
}

.prettierrc 配置

// .prettierrc.json
"@refinist/prettier-config"

prettier.config.js / prettier.config.mjs 配置

// prettier.config.js
export { default } from '@refinist/prettier-config';

规则覆盖

// prettier.config.js
import config from '@refinist/prettier-config';
/** @type {import('prettier').Config} */
export default {
  ...config

  /* 你的自定义配置 */
};

[!TIP] 更多 Prettier 配置选项，请参考 官方文档

顺便说一下，我喜欢的配置方法是 package.json 😬

npm create vue@latest

如果你使用了 Vue 官方脚手架，也就是 npm create vue@latest 来创建项目，以下是与官方模板快速集成的几个步骤：

如果你选择了 eslint 和 prettier

1. 移除 相关包和文件

• @vue/eslint-config-prettier
• @vue/eslint-config-typescript
• eslint-plugin-vue
• .prettierrc.json 文件

[!TIP] 保留 eslint 和 prettier 包

2. 安装 @refinist/eslint-config 和 @refinist/prettier-config

pnpm add -D @refinist/eslint-config @refinist/prettier-config

3. 配置 eslint.config.ts

// eslint.config.ts
import { refinist } from '@refinist/eslint-config';
export default refinist();

4. 配置 prettier

// package.json
{
  "prettier": "@refinist/prettier-config"
}

5. 配置 scripts

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

6. 验证/修复

pnpm run lint
pnpm run lint:fix

[!WARNING] 如果你的 ESLint 配置文件是 .ts 并且在运行 pnpm run lint 时遇到错误，这是因为你没有 jiti 库作为依赖。参考链接，或者你可以简单地切换到 eslint.config.js 而不是使用 .ts，这也很好用！

完成！

[!TIP] 如果你没有选择 eslint 和 prettier，请将上面的步骤 1 替换为 pnpm add -D eslint 和 pnpm add -D prettier，然后继续上面的步骤！

VS Code 设置

// .vscode/settings.json
{
  "editor.formatOnSave": false,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

受 @sxzz 和 @antfu 启发

许可证

MIT

Copyright (c) 2025-present, Zhifeng (Jeff) Wang