eslint-plugin-vitarx

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

特性

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

安装

# 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 中：

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 中：

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

与 TypeScript ESLint 配合使用

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 规范：

// 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 规则以避免冲突：

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 | 禁止解构 reactive/shallowReactive 对象，会丢失响应性 | error | | no-reactive-reassign | 禁止对 reactive 变量整体赋值，会丢失响应性 | error | | no-shallow-ref-mutation | 禁止修改 shallowRef 的内部属性，不会触发更新 | error | | no-shallow-reactive-nested-mutation | 禁止修改 shallowReactive 的嵌套属性，不会触发更新 | error | | prefer-ref-for-primitive | 基本类型应使用 ref 而非 reactive | error | | no-readonly-mutation | 禁止修改 readonly/shallowReadonly 代理的属性 | error |

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

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

JSX 模板（vitarx 专属）

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

最佳实践（vitarx 专属）

| 规则 | 说明 | 默认级别 | |--------------------------------------------------------------------------------|----------------------------|------| | no-watch-effect-async-callback | watchEffect 回调不应为 async 函数 | warn | | no-computed-side-effect | computed getter 中不应产生副作用 | warn |

通用 JSX 语法规范

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

通用 JSX 最佳实践

| 规则 | 说明 | 默认级别 | |----------------------------------------------------------------|--------------|-------| | jsx-no-duplicate-props | 禁止重复的 JSX 属性 | error |

配置说明

recommended 预设

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

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

import vitarx from "eslint-plugin-vitarx"

export default [vitarx.configs.recommended]

自定义配置

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

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 | TypeScript 代码规范 | | eslint-plugin-jsx-a11y | JSX 可访问性检查 |

License

MIT