UnoCSS ESLint 官方配置指南unocss/eslint-config 的用法、四条规则与源码实现解析【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocss本篇指南围绕 UnoCSS 官方 ESLint 集成包unocss/eslint-config展开覆盖安装方式、Flat Config 与 legacy.eslintrc两种配置风格的接入方法、全部四条内置规则order、order-attributify、blocklist、enforce-class-compile的完整选项说明并结合仓库中packages-integrations/eslint-plugin的源码实现解释默认规则集、规则前缀命名差异与自动修复fixable的底层工作方式帮助你在项目中规范原子类顺序、拦截禁用工具类并与 compile-class 转换器协同工作。一、这是什么unocss/eslint-config 的定位unocss/eslint-config是 UnoCSS 提供的 ESLint 配置包用于在代码提交/保存阶段对模板与脚本中的 UnoCSS 类名做静态检查核心能力包括强制 class 选择器按规则排序order强制 attributify 属性按规则排序order-attributify拦截命中blocklist的工具类blocklist可选开启强制 class 属性以:uno:前缀开头配合 compile-class 转换器enforce-class-compile可选开启。该包本身非常薄实际规则全部由unocss/eslint-plugin实现。从源码结构看eslint-config 包 的唯一依赖就是unocss/eslint-pluginworkspace 引用它只负责以两种配置风格“打包”出即开即用的配置对象入口.legacy见 src/index.ts内容为extends: [plugin:unocss/recommended]供.eslintrc风格extends使用入口./flat见 src/flat.ts即export default plugin.configs.flat供 ESLint Flat Config 直接放入数组使用。两条入口最终都落在 eslint-plugin 的规则注册表 上那里注册了全部四条规则// packages-integrations/eslint-plugin/src/plugin.ts export const plugin: UnoCSSEslintPlugin { rules: { order, order-attributify: orderAttributify, blocklist, enforce-class-compile: enforceClassCompile, }, }二、安装按所用包管理器安装到开发依赖中pnpm add -D unocss/eslint-configyarn add -D unocss/eslint-confignpm install -D unocss/eslint-configbun add -D unocss/eslint-config三、接入方式Flat Config 与 legacy .eslintrc3.1 Flat Config 风格eslint.config.jsimport unocss from unocss/eslint-config/flat export default [ unocss, // other configs ]从源码看unocss这个配置对象就是 configs/flat.ts 导出的内容它注册了unocss插件名并默认开启两条排序规则const flatConfig: UnoCSSEslintFlatConfig { plugins: { unocss: plugin, }, rules: { unocss/order: warn, unocss/order-attributify: warn, } as const, }仓库内的测试 fixture 也给出了一个带可选规则的真实用法示例见 fixtures/eslint.config.tsimport antfu from antfu/eslint-config import unocss from ../src export default antfu( { unocss: false, svelte: false }, unocss.configs.flat, { rules: { unocss/blocklist: error, }, }, )可以看出可选规则是通过在同级配置对象中单独声明rules来覆盖/追加的。3.2 legacy.eslintrc风格{ extends: [ unocss ] }对应的 recommended 配置 为const recommendedConfig: UnoCSSEslintRecommendedConfig { plugins: [unocss], rules: { unocss/order: warn, unocss/order-attributify: warn, } as const, }两种风格的差异汇总配置风格接入方式规则前缀Flat configimport unocss from unocss/eslint-config/flat后放入数组unocss/rule-nameLegacy.eslintrcextends: [unocss]unocss/rule-name四、内置规则总览规则默认状态作用order开启warn强制 class 选择器按 UnoCSS 解析顺序排序order-attributify开启warn强制 attributify 属性本身排序不会排序 attributify 值内部的工具类如un-beforetext-center font-sans color-gray内部内容不会被排序blocklist可选命中blocklist的类名报错可自定义提示文案enforce-class-compile可选强制 class 属性/指令以:uno:前缀开头配合 compile-class transformer4.1order类名顺序检查order规则检查 class 字符串中的工具类顺序是否与 UnoCSS 实际输出顺序一致。它支持fixable: code自动修复其 schema 定义于 rules/order.ts。适用位置规则不仅检查模板里的class属性还会检查 JS/TS 代码中“看起来像 UnoCSS 类名”的位置通过两个选项来识别unoFunctions(string[]) —— 匹配函数名的函数调用如clsx(text-center, ...)。注意是普通名称精确匹配大小写不敏感不是模式。默认值[clsx, classnames]。unoVariables(string[]) —— 匹配变量声明名的正则自动附加i标志。默认值[^cls, classNames?$]例如会命中变量名clsButton、buttonClassNames。默认值可以在源码中直接确认// rules/order.ts defaultOptions: [ { unoFunctions: [clsx, classnames], unoVariables: [^cls, classNames?$], // for example clsButton or buttonClassNames {} }, ],自定义示例Flat Config{ rules: { unocss/order: [warn, { unoFunctions: [clsx, classnames, cva], unoVariables: [^cls, classNames?$], }], }, }源码级实现要点order规则拿到候选类名字符串后并不是自己排序而是通过 rules/_.ts 中的syncAction把sort操作委托给一个 UnoCSS worker排序结果来自真实的 UnoCSS 解析流程并使用context.settings.unocss?.configPath指向的 UnoCSS 配置——也就是说排序基准与你项目里uno.config.ts的实际解析结果保持一致而不是硬编码的一套顺序。相关测试见 order.test.ts。4.2order-attributifyattributify 属性顺序开启preset-attributify时模板上会出现大量 attributify 属性如un-bg、un-text等。order-attributify会对这些属性名本身排序。注意其边界它不会进入属性值内部去排序值里拼写的工具类值内部顺序交给order规则处理。4.3blocklist拦截禁用类可选当命中blocklist中列出的工具类时抛出警告或错误。blocklist支持“类名/正则 自定义提示”的元组形式你可以借助规则meta对象的message属性给出更有上下文价值的提示export default defineConfig({ blocklist: [ [bg-red-500, { message: Use bg-red-600 instead }], [/-auto$/, { message: s Use ${s.replace(/-auto$/, -a)} instead }], // - my-auto is in blocklist: Use my-a instead ], })规则实现见 rules/blocklist.ts 及其测试 blocklist.test.ts。4.4enforce-class-compile配合 compile-class 的前缀强制可选该规则设计为与 compile class transformer 配合使用当类属性或指令不是以:uno:开头时抛出警告或错误同时该规则带有 wrench--fix能力--fix时会自动给所有 class 属性与指令补上:uno:前缀。选项默认值来自 rules/enforce-class-compile.ts 的 schema 与defaultOptionsprefix(string) —— 可与 transformer-compile-class 的自定义前缀 组合使用。默认:uno:enableFix(boolean) —— 设为false时可仅提示不修复适合渐进式迁移。默认true源码中的默认值defaultOptions: [{ prefix: :uno:, enableFix: true }],注意当前仅支持 Vue。源码中JSXAttribute与SvelteAttribute的访问器目前是todo: add support | NEED HELP占位见 rules/enforce-class-compile.ts。如果你需要 Svelte 场景下的同类能力可以关注 svelte-scoped 模式欢迎以 PR 形式为 JSX 场景贡献支持。五、如何开启可选规则blocklist与enforce-class-compile默认不启用。在配置中显式声明即可Flat Configeslint.config.jsimport unocss from unocss/eslint-config/flat export default [ unocss, { rules: { unocss/rule-name: warn, // or error, unocss/another-rule-name: [warn /* or error */, { /* options */ }], }, }, ]Legacy.eslintrc{ extends: [ unocss ], rules: { unocss/rule-name: warn, // or error, unocss/another-rule-name: [warn /* or error */, { /* options */ }] } }例如开启 blocklist 并让enforce-class-compile先只警告不自动修复{ rules: { unocss/blocklist: error, unocss/enforce-class-compile: [warn, { prefix: :uno:, enableFix: false }], }, }六、与 UnoCSS 配置的联动settings.unocss.configPath一个容易被忽略的细节order规则在检查时通过context.settings.unocss?.configPath读取 UnoCSS 配置文件路径见 rules/order.ts排序操作经由 worker 走真实的 UnoCSS 解析流程完成。这意味着规则结果会跟随你的 preset、shortcut、transformer 等配置变化——这也是为什么在 fixture 目录中同时提供了 uno.config.ts 与 eslint.config.ts 成对存在的测试夹具。若未显式配置settings.unocss.configPath规则将按默认路径约定解析项目配置跨目录 monorepo 场景建议显式指定。七、致谢Prior ArtUnoCSS 的 ESLint 插件开发参考并感谢社区项目eslint-plugin-unocss作者 devunt官方集成在其思路基础上演进为当前unocss/eslint-pluginunocss/eslint-config的形态。八、小结关注点结论包名unocss/eslint-config实现位于unocss/eslint-pluginFlat 接入import unocss from unocss/eslint-config/flat前缀unocss/Legacy 接入extends: [unocss]前缀unocss/默认规则order、order-attributify均为warn均支持--fix可选规则blocklist读取uno.config.ts的 blocklist可自定义 message、enforce-class-compileprefix默认:uno:enableFix默认true当前仅 Vue排序基准来自真实 UnoCSS 解析worker settings.unocss.configPath与项目配置一致如需查看完整实现可从 plugin.ts规则注册、configs/flat.tsFlat 默认配置与packages-integrations/eslint-plugin/src/rules/目录下的各规则文件入手。【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 UnoCSS ESLint 官方配置指南：@unocss/eslint-config 的用法、四条规则与源码实现解析
UnoCSS ESLint 官方配置指南unocss/eslint-config 的用法、四条规则与源码实现解析【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocss本篇指南围绕 UnoCSS 官方 ESLint 集成包unocss/eslint-config展开覆盖安装方式、Flat Config 与 legacy.eslintrc两种配置风格的接入方法、全部四条内置规则order、order-attributify、blocklist、enforce-class-compile的完整选项说明并结合仓库中packages-integrations/eslint-plugin的源码实现解释默认规则集、规则前缀命名差异与自动修复fixable的底层工作方式帮助你在项目中规范原子类顺序、拦截禁用工具类并与 compile-class 转换器协同工作。一、这是什么unocss/eslint-config 的定位unocss/eslint-config是 UnoCSS 提供的 ESLint 配置包用于在代码提交/保存阶段对模板与脚本中的 UnoCSS 类名做静态检查核心能力包括强制 class 选择器按规则排序order强制 attributify 属性按规则排序order-attributify拦截命中blocklist的工具类blocklist可选开启强制 class 属性以:uno:前缀开头配合 compile-class 转换器enforce-class-compile可选开启。该包本身非常薄实际规则全部由unocss/eslint-plugin实现。从源码结构看eslint-config 包 的唯一依赖就是unocss/eslint-pluginworkspace 引用它只负责以两种配置风格“打包”出即开即用的配置对象入口.legacy见 src/index.ts内容为extends: [plugin:unocss/recommended]供.eslintrc风格extends使用入口./flat见 src/flat.ts即export default plugin.configs.flat供 ESLint Flat Config 直接放入数组使用。两条入口最终都落在 eslint-plugin 的规则注册表 上那里注册了全部四条规则// packages-integrations/eslint-plugin/src/plugin.ts export const plugin: UnoCSSEslintPlugin { rules: { order, order-attributify: orderAttributify, blocklist, enforce-class-compile: enforceClassCompile, }, }二、安装按所用包管理器安装到开发依赖中pnpm add -D unocss/eslint-configyarn add -D unocss/eslint-confignpm install -D unocss/eslint-configbun add -D unocss/eslint-config三、接入方式Flat Config 与 legacy .eslintrc3.1 Flat Config 风格eslint.config.jsimport unocss from unocss/eslint-config/flat export default [ unocss, // other configs ]从源码看unocss这个配置对象就是 configs/flat.ts 导出的内容它注册了unocss插件名并默认开启两条排序规则const flatConfig: UnoCSSEslintFlatConfig { plugins: { unocss: plugin, }, rules: { unocss/order: warn, unocss/order-attributify: warn, } as const, }仓库内的测试 fixture 也给出了一个带可选规则的真实用法示例见 fixtures/eslint.config.tsimport antfu from antfu/eslint-config import unocss from ../src export default antfu( { unocss: false, svelte: false }, unocss.configs.flat, { rules: { unocss/blocklist: error, }, }, )可以看出可选规则是通过在同级配置对象中单独声明rules来覆盖/追加的。3.2 legacy.eslintrc风格{ extends: [ unocss ] }对应的 recommended 配置 为const recommendedConfig: UnoCSSEslintRecommendedConfig { plugins: [unocss], rules: { unocss/order: warn, unocss/order-attributify: warn, } as const, }两种风格的差异汇总配置风格接入方式规则前缀Flat configimport unocss from unocss/eslint-config/flat后放入数组unocss/rule-nameLegacy.eslintrcextends: [unocss]unocss/rule-name四、内置规则总览规则默认状态作用order开启warn强制 class 选择器按 UnoCSS 解析顺序排序order-attributify开启warn强制 attributify 属性本身排序不会排序 attributify 值内部的工具类如un-beforetext-center font-sans color-gray内部内容不会被排序blocklist可选命中blocklist的类名报错可自定义提示文案enforce-class-compile可选强制 class 属性/指令以:uno:前缀开头配合 compile-class transformer4.1order类名顺序检查order规则检查 class 字符串中的工具类顺序是否与 UnoCSS 实际输出顺序一致。它支持fixable: code自动修复其 schema 定义于 rules/order.ts。适用位置规则不仅检查模板里的class属性还会检查 JS/TS 代码中“看起来像 UnoCSS 类名”的位置通过两个选项来识别unoFunctions(string[]) —— 匹配函数名的函数调用如clsx(text-center, ...)。注意是普通名称精确匹配大小写不敏感不是模式。默认值[clsx, classnames]。unoVariables(string[]) —— 匹配变量声明名的正则自动附加i标志。默认值[^cls, classNames?$]例如会命中变量名clsButton、buttonClassNames。默认值可以在源码中直接确认// rules/order.ts defaultOptions: [ { unoFunctions: [clsx, classnames], unoVariables: [^cls, classNames?$], // for example clsButton or buttonClassNames {} }, ],自定义示例Flat Config{ rules: { unocss/order: [warn, { unoFunctions: [clsx, classnames, cva], unoVariables: [^cls, classNames?$], }], }, }源码级实现要点order规则拿到候选类名字符串后并不是自己排序而是通过 rules/_.ts 中的syncAction把sort操作委托给一个 UnoCSS worker排序结果来自真实的 UnoCSS 解析流程并使用context.settings.unocss?.configPath指向的 UnoCSS 配置——也就是说排序基准与你项目里uno.config.ts的实际解析结果保持一致而不是硬编码的一套顺序。相关测试见 order.test.ts。4.2order-attributifyattributify 属性顺序开启preset-attributify时模板上会出现大量 attributify 属性如un-bg、un-text等。order-attributify会对这些属性名本身排序。注意其边界它不会进入属性值内部去排序值里拼写的工具类值内部顺序交给order规则处理。4.3blocklist拦截禁用类可选当命中blocklist中列出的工具类时抛出警告或错误。blocklist支持“类名/正则 自定义提示”的元组形式你可以借助规则meta对象的message属性给出更有上下文价值的提示export default defineConfig({ blocklist: [ [bg-red-500, { message: Use bg-red-600 instead }], [/-auto$/, { message: s Use ${s.replace(/-auto$/, -a)} instead }], // - my-auto is in blocklist: Use my-a instead ], })规则实现见 rules/blocklist.ts 及其测试 blocklist.test.ts。4.4enforce-class-compile配合 compile-class 的前缀强制可选该规则设计为与 compile class transformer 配合使用当类属性或指令不是以:uno:开头时抛出警告或错误同时该规则带有 wrench--fix能力--fix时会自动给所有 class 属性与指令补上:uno:前缀。选项默认值来自 rules/enforce-class-compile.ts 的 schema 与defaultOptionsprefix(string) —— 可与 transformer-compile-class 的自定义前缀 组合使用。默认:uno:enableFix(boolean) —— 设为false时可仅提示不修复适合渐进式迁移。默认true源码中的默认值defaultOptions: [{ prefix: :uno:, enableFix: true }],注意当前仅支持 Vue。源码中JSXAttribute与SvelteAttribute的访问器目前是todo: add support | NEED HELP占位见 rules/enforce-class-compile.ts。如果你需要 Svelte 场景下的同类能力可以关注 svelte-scoped 模式欢迎以 PR 形式为 JSX 场景贡献支持。五、如何开启可选规则blocklist与enforce-class-compile默认不启用。在配置中显式声明即可Flat Configeslint.config.jsimport unocss from unocss/eslint-config/flat export default [ unocss, { rules: { unocss/rule-name: warn, // or error, unocss/another-rule-name: [warn /* or error */, { /* options */ }], }, }, ]Legacy.eslintrc{ extends: [ unocss ], rules: { unocss/rule-name: warn, // or error, unocss/another-rule-name: [warn /* or error */, { /* options */ }] } }例如开启 blocklist 并让enforce-class-compile先只警告不自动修复{ rules: { unocss/blocklist: error, unocss/enforce-class-compile: [warn, { prefix: :uno:, enableFix: false }], }, }六、与 UnoCSS 配置的联动settings.unocss.configPath一个容易被忽略的细节order规则在检查时通过context.settings.unocss?.configPath读取 UnoCSS 配置文件路径见 rules/order.ts排序操作经由 worker 走真实的 UnoCSS 解析流程完成。这意味着规则结果会跟随你的 preset、shortcut、transformer 等配置变化——这也是为什么在 fixture 目录中同时提供了 uno.config.ts 与 eslint.config.ts 成对存在的测试夹具。若未显式配置settings.unocss.configPath规则将按默认路径约定解析项目配置跨目录 monorepo 场景建议显式指定。七、致谢Prior ArtUnoCSS 的 ESLint 插件开发参考并感谢社区项目eslint-plugin-unocss作者 devunt官方集成在其思路基础上演进为当前unocss/eslint-pluginunocss/eslint-config的形态。八、小结关注点结论包名unocss/eslint-config实现位于unocss/eslint-pluginFlat 接入import unocss from unocss/eslint-config/flat前缀unocss/Legacy 接入extends: [unocss]前缀unocss/默认规则order、order-attributify均为warn均支持--fix可选规则blocklist读取uno.config.ts的 blocklist可自定义 message、enforce-class-compileprefix默认:uno:enableFix默认true当前仅 Vue排序基准来自真实 UnoCSS 解析worker settings.unocss.configPath与项目配置一致如需查看完整实现可从 plugin.ts规则注册、configs/flat.tsFlat 默认配置与packages-integrations/eslint-plugin/src/rules/目录下的各规则文件入手。【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考