cqrcb-eslint-modern配置规范

1. 项目概述

本规范是基于 ESLint 9 的 FlatConfig 架构设计的现代化 ESLint 配置方案， 旨在为多语言/框架项目提供统一的代码风格管理解决方案。

目录结构说明

• eslint/  # 存放各类语言/框架的 ESLint 规范配置
• scripts/  # 安装脚本（自动执行初始化配置）
• index.mjs  # 主配置入口（默认合并 JS/TS/Vue/React 规范）

2. 安装与使用

安装命令

npm install cqrcb-eslint-modern -D

自动初始化

安装完成后会在项目根目录生成配置文件：

• .gitignore
• .husky/（含预提交钩子）
• .eslint.config.mjs（ESLint 配置）
• 在 package.json 中追加脚本命令

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

配置选择

• 默认配置：直接使用 index.mjs（已合并 JS/TS/Vue/React 规范）
• 自定义配置：修改 .eslint.config.mjs 按需选择规范

3. 注意事项

TypeScript 支持

• 对于ts的eslint规范，必须手动创建 tsconfig.json 文件
• 推荐基础配置

  {
    "compilerOptions": {
      "jsx": "preserve",
      "module": "ESNext",
      "target": "ESNext"
    }
  }

文件匹配模式

⚠️ 重要：单文件类型不需要使用花括号 {}，否则会导致解析失败 ✅ 正确写法： files: ['**/*.ts'] ❌ 错误写法： files: ['**/*.{ts}']

配置文件类型选择

| 文件后缀 | 是否需要defineConfig | 类型提示 | 适用场景 | | :----: | :----: | :----: | :----: | | .js | ❌ 不需要 | ❌ 无 | 简单项目 | | .cjs | ❌ 不需要 | ❌ 无 | CommonJS | | .ts | ✅ 推荐 | ✅ 有 | 需要类型安全 | | .cts | ✅ 推荐 | ✅ 有 | CommonJS + TS |

插件使用原则

• ESLint 原生支持的文件类型（如 .js）无需额外插件
• 特殊文件类型（如 .vue、.jsx）需要安装对应插件

4. 已知问题

1. 依赖冗余

当前安装方案会包含所有语言/框架的解析器和插件（即使项目未使用），例如： 即使未使用 TypeScript，仍会安装@typescript-eslint/parser， 后续版本将优化为按需安装

2. 对css的检测

未配置对css规范的检测 "*.{css,scss}": ["stylelint --fix", "prettier --write"]

3. 未经过babel转译，对低版本兼容性较低

说明：如果对esm进行编译，但项目根路径的.eslint.config.mjs 会import本pkg中的mjs，但经过编译的mjs似乎不支持import， 因此放弃了babel转译

4. setup.mjs格式

setup.mjs的后缀不强制，也可以写成cjs风格

5. esm/cjs处理

对于.js文件，有的是esm格式，有的是cjs格式，这种处理起来比较麻烦， 目前是直接在javascript里面为module，require添加声明， 但esm和cjs始终存在混合问题，后续想针对.mjs和.cjs再进行细化的规范处理

export default [
  {
    files: ['**/*.cjs'],
    languageOptions: {
      // 关键配置 1: 声明 CommonJS 模块类型
      sourceType: 'commonjs',
      // 关键配置 2: 启用 Node.js 环境
      globals: {
        module: 'writable',  // CommonJS 的 module 是可写的
        require: 'readonly',
        exports: 'writable',
        __dirname: 'readonly',
        __filename: 'readonly'
      }
    }
  },
];