# Fast.ESLint.Config

**Repository Path**: FastDotnet/Fast.ESLint.Config

## Basic Information

- **Project Name**: Fast.ESLint.Config
- **Description**: Fast 平台下基于 ESLint Flag 构建的规则库。
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://fastdotnet.com
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-14
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="left">
	<strong>简体中文</strong> | <a href="./README.md">English</a>
</p>

<p align="center">
	<img src="./Fast.png" alt="logo" width="160" />
</p>

# @fast-china/eslint-config

面向 Vue 3、UniApp、SDK、Node.js、React、Angular、TypeScript 与 JavaScript 项目的实用型 ESLint Flat Config。

规则取舍遵循：先尊重社区通用写法并保持代码简洁、易读，再依次考虑真实 Bug / 类型安全、代码一致性和 Fast 系列项目偏好。不会为了满足 ESLint 强制改写语义正常、普遍使用的代码。

## 特性

- 基于 ESLint 10，仅提供原生 Flat Config。
- Vue 3 与 UniApp 使用两个独立完整配置；普通 Vue 项目不会获得 UniApp globals、`.nvue` 解析或清单适配。
- TypeScript 使用 `recommendedTypeChecked` 与 Project Service，不叠加完整 strict/stylistic 预置。
- `.ts`、`.mts`、`.cts` 导出边界按 SDK 公共 API 对待；`.tsx` 保留完整类型安全和常见组件返回类型推断。
- JavaScript、TypeScript、Import 与 RegExp 规则在 SDK 和应用项目之间保持一致。
- 默认统一排序 `package.json` 和 `tsconfig*.json`；React、Angular、Markdown 和 Lodash 通过 `./configs` 按需组合。
- 根据规则 schema 生成精确 `RuleOptions`，提供规则名和选项自动补全。

## 环境要求

- Node.js `^22.18.0` 或 `^24.18.0`
- ESLint `^10.0.0`
- TypeScript `^6.0.0`

```sh
pnpm add -D eslint typescript @fast-china/eslint-config
```

## Vue 3

```js
import { vueConfig } from "@fast-china/eslint-config";
import { defineConfig } from "eslint/config";

export default defineConfig([
	...vueConfig,
	{
		name: "project/custom",
		rules: {
			"no-console": "warn",
		},
	},
]);
```

该入口处理 JavaScript、类型感知 TypeScript、Vue SFC，以及 Vue 项目常用的独立 `.jsx`/`.tsx` 组件文件；Vue JSX/TSX 继续检查显式 emits、重复键、只读 props、响应性丢失和保留组件名，但不会套用模板专属的 kebab-case、模板属性排序或 `v-text`/`v-html` 规则。配置同时包含 JSON、Import、RegExp、`.gitignore` 和 Prettier 兼容规则，但不包含任何 UniApp 能力。

## UniApp

```js
import { uniAppConfig } from "@fast-china/eslint-config";
import { defineConfig } from "eslint/config";

export default defineConfig([
	...uniAppConfig,
	{
		name: "project/custom",
		ignores: ["src/generated/**"],
		rules: {
			"no-console": "warn",
		},
	},
]);
```

UniApp 入口在 Vue 完整能力之外增加 `.nvue`、`uni`、`uniCloud`、页面 API、条件编译平台 globals、`unpackage` 忽略，以及 `pages.json`、`manifest.json` 注释适配。

ESLint 不执行 `#ifdef`/`#endif`，因此只能识别平台对象，不能验证对象是否位于正确的平台分支。当前不处理需要专用解析器的 `.uvue` 与 `.uts`。

## 工厂与项目覆写

根入口只提供含义明确的具名配置与工厂。项目需要选择运行环境或追加覆写时使用对应工厂：

```js
import { createVueProjectConfigs, defineRules } from "@fast-china/eslint-config";
import { defineConfig } from "eslint/config";

export default defineConfig([
	...createVueProjectConfigs({ environment: "universal" }),
	{
		name: "project/custom",
		ignores: ["public/vendor/**"],
		languageOptions: {
			globals: {
				__APP_VERSION__: "readonly",
			},
		},
		rules: defineRules({
			"no-console": "warn",
		}),
	},
]);
```

可用工厂：

- `createVueProjectConfigs(options, ...overrides)`
- `createUniAppProjectConfigs(options, ...overrides)`
- `createBaseConfigs(options)`：不绑定前端框架，适用于 Node.js、SDK 及其他显式组合场景

`environment` 可为 `"browser"`、`"node"` 或 `"universal"`，默认是 `"browser"`。配置文件、脚本、测试和 CLI 文件始终单独获得 Node.js globals。

后置 Flat Config 拥有最高优先级。`defineRules()` 不修改传入对象，只提供精确规则类型检查。

## TypeScript 策略

类型感知文件必须属于 Project Service 可发现的 `tsconfig.json`。

- `explicit-module-boundary-types: "error"`：`.ts`、`.mts`、`.cts` 导出函数及导出类的公共边界必须显式声明参数和返回类型。
- `.tsx` 默认关闭模块边界类型强制：组件 Props 继续接受 TypeScript 检查，但不要求补写可稳定推断的 JSX 返回类型。
- `explicit-function-return-type: "off"`：内部函数、局部处理函数和内联回调使用 TypeScript 推断。
- `no-inferrable-types` 不删除参数和属性上的显式类型。
- Vue/NVue SFC 与独立 TSX 组件不强制模块边界和函数返回类型，以保留常见简洁写法。
- `no-floating-promises` 关闭；是否等待 Promise 由业务顺序和异常语义决定。
- `no-void: "error"`：不使用 `void promise` 或其他 `void` 表达式规避检查。
- `require-await: "error"`：没有真实 `await` 的函数应删除 `async`，避免改变返回值和异常语义。
- `no-misused-promises`、`await-thenable`、unsafe 类型规则及精选的高置信度类型规则保持为错误。
- 标准非空断言可用；矛盾、重复或无效的断言仍由专项规则检查。
- 数字和布尔值可直接用于模板字符串；运行时防御性条件不会因类型看似多余而报错。

## JavaScript、Import 与 Vue 策略

- `no-empty` 允许完全空的 `catch`，其他空代码块仍报错。
- `camelcase: ["error", { properties: "never" }]`：变量和类型使用 camelCase，外部协议对象属性保持原名。
- `no-eval`、`no-implied-eval`、`no-new-func`、`no-debugger` 等真实风险规则为错误。
- `import-x/first`、`import-x/no-duplicates` 与 `import-x/order` 均为错误；声明顺序支持自动修复。
- 保留 UniApp、Vue、React、Angular、Vite、Element Plus、Fast 和 Lodash 等常用 pathGroups，`@/**` 归入 internal，类型导入不参与 pathGroups 匹配。
- `sort-imports` 只检查同一 import 声明 `{}` 内的成员顺序，不接管声明之间的排序。
- `import-x/style-imports-last` 要求样式文件形成最后一个连续分组，同时不改变样式组内部顺序。
- Vue SFC 使用官方 `flat/recommended`；显式 emits、重复键、只读 props、响应性丢失和保留组件名等脚本语义规则也应用于 Vue JSX/TSX。
- kebab-case 属性、模板属性顺序和组件上的 `v-text`/`v-html` 仅检查 `.vue/.nvue` 模板；JSX 属性继续遵循 JavaScript 的 camelCase 约定。`no-v-html` 保持警告。

## React 与 Angular

```js
import { createBaseConfigs } from "@fast-china/eslint-config";
import { createReactConfigs } from "@fast-china/eslint-config/configs";
import { defineConfig } from "eslint/config";

export default defineConfig([
	...createBaseConfigs(),
	...createReactConfigs(),
	{
		name: "project/custom",
		rules: { "no-console": "warn" },
	},
]);
```

Angular 同理组合 `createAngularConfigs()`。基础配置不会加载 Vue 或 UniApp。

## 可选能力与清单排序

Markdown 和 Lodash 导入策略需要显式组合：

```js
import { createBaseConfigs } from "@fast-china/eslint-config";
import { createMarkdownConfigs } from "@fast-china/eslint-config/configs";
import { defineConfig } from "eslint/config";

export default defineConfig([
	...createBaseConfigs({ environment: "node" }),
	...createMarkdownConfigs(),
	{
		name: "project/custom",
		rules: { "no-console": "warn" },
	},
]);
```

`createBaseConfigs()`、`vueConfig` 和 `uniAppConfig` 都默认启用 `package.json` 与 `tsconfig*.json` 排序。`package.json` 排序不会进入顺序具有运行时语义的条件 `exports` 对象。

## 公共入口

- `@fast-china/eslint-config`：具名导出两个完整配置、项目配置工厂、`defineRules`、`ProjectConfigOptions` 和 `RuleOptions`；不提供默认导出或旧入口别名。
- `@fast-china/eslint-config/configs`：框架和可选功能片段。
- `@fast-china/eslint-config/constants`：文件 glob 与 UniApp globals。
- `@fast-china/eslint-config/rules`：带类型的原始规则记录。

## Prettier

Prettier 不作为 ESLint 规则运行。默认配置只加载 `eslint-config-prettier` 关闭冲突规则；项目需要自行安装并执行格式化。

## 文档

- [完整规则手册](./docs/rules/index.zh.md)
- [默认规则与风险指南](./docs/rules-risk.zh.md)
- [工程质量审查报告](./docs/engineering-audit.zh.md)
- [更新日志](./CHANGELOG.md)

完整规则手册在每个分类中优先列出仓库显式配置的规则，再列第三方预置规则；全部规则均提供直接的错误与正确代码示例。

## 开发

```sh
pnpm install --frozen-lockfile
pnpm typegen
pnpm check
```