# eslint-plugin

**Repository Path**: vitarx/eslint-plugin

## Basic Information

- **Project Name**: eslint-plugin
- **Description**: Official ESLint plugin for Vitarx framework.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-06-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# eslint-plugin-vitarx

[Vitarx](https://vitarx.cn) 框架官方 ESLint 插件，提供针对 vitarx 响应式系统、组件生命周期、JSX 模板语法的静态检查规则，以及通用 JSX 代码规范规则。

## 特性

- **32 条规则** — 17 条 vitarx 专属规则 + 15 条通用 JSX 规则
- **零配置启动** — 提供 `recommended` 预设配置，开箱即用
- **TypeScript 优先** — 完整的 TypeScript 类型支持
- **Flat Config** — 支持 ESLint 9+ 的扁平配置格式，同时兼容 ESLint 8
- **自动修复** — 多条规则支持 `--fix` 自动修复

## 安装

```bash
# npm
npm install -D eslint-plugin-vitarx

# pnpm
pnpm add -D eslint-plugin-vitarx

# yarn
yarn add -D eslint-plugin-vitarx
```

### 前置依赖

| 包            | 版本                   |
|--------------|----------------------|
| `eslint`     | `^8.57.0` 或 `^9.0.0` |
| `vitarx`     | `^4.0.0`             |
| `typescript` | `>= ^5.0.0`（推荐）      |

## 使用方式

### ESLint 9+（Flat Config）

在 `eslint.config.js` 中：

```js
import vitarx from "eslint-plugin-vitarx"

export default [
  // 使用 recommended 预设（推荐）
  vitarx.configs.recommended,

  // 或者手动配置
  {
    plugins: {
      vitarx
    },
    rules: {
      "vitarx/no-reactive-destructure": "error",
      "vitarx/no-async-lifecycle-call": "error"
      // ... 按需启用
    }
  }
]
```

### ESLint 8（Legacy Config）

在 `.eslintrc.js` 中：

```js
module.exports = {
  plugins: ["vitarx"],
  rules: {
    "vitarx/no-reactive-destructure": "error",
    "vitarx/no-async-lifecycle-call": "error"
    // ... 按需启用
  }
}
```

### 与 TypeScript ESLint 配合使用

```js
import tseslint from "typescript-eslint"
import vitarx from "eslint-plugin-vitarx"

export default [
  ...tseslint.configs.recommended,
  vitarx.configs.recommended,
  {
    languageOptions: {
      parserOptions: {
        ecmaFeatures: { jsx: true }
      }
    }
  }
]
```

### 最佳配置实践

以下是生产项目推荐的完整配置，结合 `typescript-eslint` + `eslint-plugin-vitarx`，覆盖类型检查、vitarx 框架规则和通用 JSX 规范：

```js
// eslint.config.{js,ts}
import { defineConfig } from 'eslint/config'
import tseslint from 'typescript-eslint'
import eslintPluginVitarx from 'eslint-plugin-vitarx'

export default defineConfig(
  // 忽略 node_modules 和 dist 目录
  { ignores: ['**/node_modules/**', '**/dist/**'] },
  // TypeScript 配置：推荐规则
  ...tseslint.configs.recommended,
  // 基础配置：推荐规则
  eslintPluginVitarx.configs.recommended,
  // 全局配置：JSX + TypeScript 解析器
  {
    languageOptions: {
      parserOptions: {
        ecmaFeatures: { jsx: true }
      }
    }
  },
  // 启用类型感知规则（可选，需要 tsconfig.json）
  {
    files: ['src/**/*.{ts,tsx}'],
    extends: [...tseslint.configs.recommendedTypeChecked],
    languageOptions: {
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname
      }
    }
  },
  // Prettier 已处理这些格式化规则，关闭以避免冲突（可选）
  {
    rules: {
      "vitarx/jsx-indent": "off",
      "vitarx/jsx-indent-props": "off",
      "vitarx/jsx-closing-bracket-location": "off",
      "vitarx/jsx-closing-tag-location": "off",
      "vitarx/jsx-first-prop-new-line": "off",
      "vitarx/jsx-max-props-per-line": "off",
      "vitarx/jsx-one-expression-per-line": "off",
      "vitarx/jsx-tag-spacing": "off",
      "vitarx/jsx-curly-brace-presence": "off",
      "vitarx/jsx-boolean-value": "off",
      "vitarx/jsx-self-closing-comp": "off",
      "vitarx/jsx-props-no-multi-spaces": "off"
    }
  }
)
```

**配置说明：**

| 步骤 | 作用                                                             |
|----|----------------------------------------------------------------|
| 1  | TypeScript 基础规则（类型安全、语法规范）                                     |
| 2  | vitarx 框架规则 + 通用 JSX 规范（开箱即用）                                  |
| 3  | 启用 JSX 解析，确保 vitarx 的 JSX 规则能正常工作                              |
| 4  | 对 `src/` 启用类型感知规则（如 `no-floating-promises`），需要 `tsconfig.json` |
| 5  | 测试目录放宽不适合的规则                                                   |
| 6  | 配置文件/脚本放宽框架专属规则                                                |

### 与 Prettier 配合使用

如果你使用 Prettier，建议关闭部分格式化类 JSX 规则以避免冲突：

```js
import vitarx from "eslint-plugin-vitarx"

export default [
  vitarx.configs.recommended,
  {
    rules: {
      // Prettier 已处理这些格式化规则，关闭以避免冲突
      "vitarx/jsx-indent": "off",
      "vitarx/jsx-indent-props": "off",
      "vitarx/jsx-closing-bracket-location": "off",
      "vitarx/jsx-closing-tag-location": "off",
      "vitarx/jsx-first-prop-new-line": "off",
      "vitarx/jsx-max-props-per-line": "off",
      "vitarx/jsx-one-expression-per-line": "off",
      "vitarx/jsx-tag-spacing": "off",
      "vitarx/jsx-curly-brace-presence": "off",
      "vitarx/jsx-boolean-value": "off",
      "vitarx/jsx-self-closing-comp": "off",
      "vitarx/jsx-props-no-multi-spaces": "off"
    }
  }
]
```

## 规则列表

### 响应式系统（vitarx 专属）

| 规则                                                                                       | 说明                                      | 默认级别  |
|------------------------------------------------------------------------------------------|-----------------------------------------|-------|
| [no-reactive-destructure](docs/rules/no-reactive-destructure.md)                         | 禁止解构 reactive/shallowReactive 对象，会丢失响应性 | error |
| [no-reactive-reassign](docs/rules/no-reactive-reassign.md)                               | 禁止对 reactive 变量整体赋值，会丢失响应性              | error |
| [no-shallow-ref-mutation](docs/rules/no-shallow-ref-mutation.md)                         | 禁止修改 shallowRef 的内部属性，不会触发更新            | error |
| [no-shallow-reactive-nested-mutation](docs/rules/no-shallow-reactive-nested-mutation.md) | 禁止修改 shallowReactive 的嵌套属性，不会触发更新       | error |
| [prefer-ref-for-primitive](docs/rules/prefer-ref-for-primitive.md)                       | 基本类型应使用 ref 而非 reactive                 | error |
| [no-readonly-mutation](docs/rules/no-readonly-mutation.md)                               | 禁止修改 readonly/shallowReadonly 代理的属性     | error |

### 组件与生命周期（vitarx 专属）

| 规则                                                                       | 说明                               | 默认级别  |
|--------------------------------------------------------------------------|----------------------------------|-------|
| [no-async-lifecycle-call](docs/rules/no-async-lifecycle-call.md)         | 禁止在 async 函数中调用生命周期钩子            | error |
| [no-async-hook-call](docs/rules/no-async-hook-call.md)                   | 禁止在 async 函数中调用组合式 Hook          | error |
| [no-async-provide-inject](docs/rules/no-async-provide-inject.md)         | 禁止在 async 函数中调用 provide/inject   | error |
| [no-define-expose-in-builder](docs/rules/no-define-expose-in-builder.md) | 禁止在 builder 视图函数中使用 defineExpose | error |

### JSX 模板（vitarx 专属）

| 规则                                                         | 说明                            | 默认级别  |
|------------------------------------------------------------|-------------------------------|-------|
| [no-ref-value-in-jsx](docs/rules/no-ref-value-in-jsx.md)   | JSX 中 ref 自动解包，不需要 .value     | warn  |
| [no-v-bind-and-spread](docs/rules/no-v-bind-and-spread.md) | v-bind 和 {...spread} 不能同时使用   | error |
| [no-v-model-on-native](docs/rules/no-v-model-on-native.md) | 禁止在原生 HTML 元素上使用 v-model      | warn  |
| [valid-v-bind](docs/rules/valid-v-bind.md)                 | v-bind 的值必须是对象或 [对象, 排除数组] 格式 | error |
| [require-for-key](docs/rules/require-for-key.md)           | For 组件应提供 key 属性              | warn  |

### 最佳实践（vitarx 专属）

| 规则                                                                             | 说明                         | 默认级别 |
|--------------------------------------------------------------------------------|----------------------------|------|
| [no-watch-effect-async-callback](docs/rules/no-watch-effect-async-callback.md) | watchEffect 回调不应为 async 函数 | warn |
| [no-computed-side-effect](docs/rules/no-computed-side-effect.md)               | computed getter 中不应产生副作用   | warn |

### 通用 JSX 语法规范

| 规则                                                                         | 说明               | 默认级别 |
|----------------------------------------------------------------------------|------------------|------|
| [jsx-self-closing-comp](docs/rules/jsx-self-closing-comp.md)               | 无子元素的组件应自闭合      | warn |
| [jsx-pascal-case](docs/rules/jsx-pascal-case.md)                           | 组件名应为 PascalCase | warn |
| [jsx-curly-brace-presence](docs/rules/jsx-curly-brace-presence.md)         | 不必要的花括号          | warn |
| [jsx-boolean-value](docs/rules/jsx-boolean-value.md)                       | 布尔属性简写一致性        | warn |
| [jsx-tag-spacing](docs/rules/jsx-tag-spacing.md)                           | JSX 标签内空格规范      | warn |
| [jsx-closing-bracket-location](docs/rules/jsx-closing-bracket-location.md) | 闭合括号位置一致性        | warn |
| [jsx-closing-tag-location](docs/rules/jsx-closing-tag-location.md)         | 闭合标签位置一致性        | warn |
| [jsx-first-prop-new-line](docs/rules/jsx-first-prop-new-line.md)           | 多行属性时第一个属性换行     | warn |
| [jsx-max-props-per-line](docs/rules/jsx-max-props-per-line.md)             | 限制每行最大属性数量       | warn |
| [jsx-sort-props](docs/rules/jsx-sort-props.md)                             | 属性排序             | off  |
| [jsx-indent](docs/rules/jsx-indent.md)                                     | JSX 缩进规范         | warn |
| [jsx-indent-props](docs/rules/jsx-indent-props.md)                         | 属性缩进规范           | warn |
| [jsx-props-no-multi-spaces](docs/rules/jsx-props-no-multi-spaces.md)       | 禁止属性间多余空格        | warn |
| [jsx-one-expression-per-line](docs/rules/jsx-one-expression-per-line.md)   | 每行一个 JSX 表达式     | warn |

### 通用 JSX 最佳实践

| 规则                                                             | 说明           | 默认级别  |
|----------------------------------------------------------------|--------------|-------|
| [jsx-no-duplicate-props](docs/rules/jsx-no-duplicate-props.md) | 禁止重复的 JSX 属性 | error |

## 配置说明

### recommended 预设

`recommended` 配置启用了所有规则，按风险等级设置默认级别：

- **error** — 可能导致运行时错误或行为异常的规则
- **warn** — 最佳实践建议和代码风格规范
- **off** — 个人偏好类规则（如 `jsx-sort-props`），默认关闭

```js
import vitarx from "eslint-plugin-vitarx"

export default [vitarx.configs.recommended]
```

### 自定义配置

你可以关闭特定规则或调整级别：

```js
import vitarx from "eslint-plugin-vitarx"

export default [
  vitarx.configs.recommended,
  {
    rules: {
      // 关闭不需要的规则
      "vitarx/no-ref-value-in-jsx": "off",
      // 将 warn 提升为 error
      "vitarx/require-for-key": "error",
      // 启用默认关闭的规则
      "vitarx/jsx-sort-props": "warn"
    }
  }
]
```

## 与其他 ESLint 插件配合

`eslint-plugin-vitarx` 内置了通用 JSX 规则。如需更多功能，可搭配以下插件：

| 插件                                                                               | 用途              |
|----------------------------------------------------------------------------------|-----------------|
| [`@typescript-eslint`](https://typescript-eslint.io)                             | TypeScript 代码规范 |
| [`eslint-plugin-jsx-a11y`](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y) | JSX 可访问性检查      |

## License

[MIT](./LICENSE)