emotion/eslint-plugin 演进全解析从 10.0.14 到 11.12.0 的规则迭代与 Emotion 迁移实践【免费下载链接】emotion‍ CSS-in-JS library designed for high performance style composition项目地址: https://gitcode.com/gh_mirrors/em/emotion本篇技术指南以emotion/eslint-plugin的 CHANGELOG 为主线系统梳理该 ESLint 插件从 10.0.14 到 11.12.0 的关键演进ESLint 版本兼容策略、TypeScript 源码迁移、jsxImportSource自动注入、空cssprop 崩溃修复以及围绕 Emotion 10/11 迁移的规则体系。读者读完本文将掌握该插件的全部规则能力与配置方法并能结合源码理解每条规则的实际判定逻辑。一、插件定位为 Emotion 而生的 ESLint 规则集emotion/eslint-plugin是 Emotion 官方维护的 ESLint 插件仓库位于packages/eslint-plugin/其核心职责有两类强制最佳实践保证cssprop 依赖的jsx已正确导入、限制样式书写风格字符串或对象二选一提供 codemod 能力帮助用户从 Emotion 10 平滑迁移到 Emotion 11甚至自动改写旧版包名导入。在 README.md 中明确给出了安装与启用方式npm i eslint --save-dev npm install emotion/eslint-plugin --save-dev注意如果 ESLint 是全局安装-g则emotion/eslint-plugin也必须全局安装否则 ESLint 无法加载插件。启用时只需在.eslintrc的plugins段填入emotion可省略/eslint-plugin后缀随后在rules段按需开启规则{ plugins: [emotion], rules: { emotion/jsx-import: error } }从src/utils.ts的源码可以看到所有规则都通过typescript-eslint/utils提供的ESLintUtils.RuleCreator创建规则元信息中的文档链接会自动指向仓库内docs/rules/${ruleName}.md保证每条规则都有配套文档可查。二、版本演进时间线从 CHANGELOG 看迭代脉络CHANGELOG 记录了从 10.0.14 到 11.12.0 的全部关键变更按时间线拆解如下。11.12.0TypeScript 迁移与空 css prop 修复最新版本这是 CHANGELOG 中最新的一个版本包含一个 Minor 和两个 Patch 变更源码迁移到 TypeScriptPR #2568插件源码由 JavaScript 迁移至 TypeScript此后类型声明文件.d.ts由 TypeScript 编译器自动生成取代了此前手写的类型声明。这一点可以在当前仓库结构中得到印证——packages/eslint-plugin/src/下的全部规则文件均为.ts后缀。空cssprop 崩溃修复div css /这种空属性的写法此前会导致emotion/syntax-preference规则崩溃现在会正常抛出一个错误而非崩溃。emotion/jsx-import规则崩溃修复同样的空cssprop 场景在jsx-import规则中也曾触发崩溃本版本一并修复。结合 syntax-preference.ts 源码可以看到两条规则都针对JSXAttribute中的css属性做了空值判断当node.value不存在时报告emptyCssProp消息Empty \css prop is not valid.从而避免访问不存在的节点属性导致崩溃。11.11.0Node ESM 导入修复该版本修复了插件在 Node ESM 环境下无法正常import的问题PR #3029。这与包导出的模块格式有关在纯 CommonJS 环境下运行正常、切换到 ESM 加载时则可能失败属于纯工程层面的兼容性修复。11.10.0exports 字段限制导入范围该版本PR #2819在package.json清单中新增了exports字段。exports字段会限制包内可被外部导入的文件范围但 Emotion 团队表示会尽量放行所有此前被视为公共 API 的文件路径避免破坏既有使用方的导入。11.7.0ESLint 8 进入 peer 依赖该版本PR #2562将 ESLint 8 加入 peerDependencies 范围同时继续支持 ESLint 6 与 ESLint 7。从 package.json 可以看到这一策略一直延续至今——插件对多个 ESLint 主版本保持向后兼容方便不同工程平滑接入。11.5.0自动注入 jsxImportSource pragma该版本PR #2353实现了jsxImportSourcepragma 的自动添加。这是为 React 17 自动 JSX runtimeruntime: automatic设计的能力具体逻辑见 jsx-import.tsconst JSX_IMPORT_SOURCE_REGEX /\*?\s*jsxImportSource\s([^\s])/当检测到cssprop 但文件中不存在/** jsxImportSource emotion/react */注释时规则会自动在文件头部插入/** jsxImportSource emotion/react */修复逻辑通过fixer.insertTextBefore(sourceCode.ast.body[0], ...)实现若已存在但指向了错误的 import source则会用fixer.replaceText直接替换为正确值。规则还支持通过配置选项指定importSource默认emotion/reactschema 中要求runtime必须等于automatic才会启用该分支。11.2.0syntax-preference 覆盖 css 函数该版本PR #2246增强了syntax-preference规则支持对css函数调用进行检查并校验css与styled调用的参数样式类型。从源码看isObjectStyle与isStringStyle两个判定函数覆盖了四种写法// 对象风格isObjectStyle css({ color: red }) styled.h1({ color: red }) // 简写 styled(h1)({ color: red }) // 完整写法 // 字符串风格isStringStyle csscolor: red; styled.h1color: red; styled(h1)color: red;当配置为object偏好时规则还会递归检查ArrayExpression中每个元素、TemplateLiteral、字符串Literal以及 JSX 中css属性的表达式容器对于字符串风格的模板字面量报告preferWrappingWithCSSPrefer wrapping your string styles with \css call.——即提示用css 标签包装。11.0.0重大重构 —— 改名、新规则与迁移体系11.0.0 是本插件历史上最重要的一次大版本包含一个 Major 变更与三个 Minor 变更插件改名PR #1675eslint-plugin-emotion正式更名为emotion/eslint-plugin。迁移动作很明确配置中的plugins: [emotion]改为plugins: [emotion]规则前缀由emotion/改为emotion/。新增emotion/pkg-renaming规则专为 Emotion 11 迁移设计的 codemod 规则详见下文。cssprop 场景尊重syntax-preferencePR #1659此前syntax-preference只检查styled/css调用现在 JSX 中的cssprop 写法对象 vs 字符串也纳入风格统一检查。ESLint 7 加入 peer 依赖范围PR #2034在继续支持 ESLint 6 的基础上扩展兼容矩阵。随后发布的11.0.0-rc.0与11.0.0-next.10只是发布候选与预发布版本内容与 11.0.0 一致。10.x 时代稳定与修补10.0.27补充 LICENSE 文件PR #1698。10.0.14更新构建工具并增强jsx-import规则的自动修复能力——当文件中已存在import ... from emotion/core时自动修复会在现有 import 语句中追加jsx具名导入而不是新增一行 import。三、规则体系深度解析当前仓库共包含 6 条规则全部源码位于packages/eslint-plugin/src/rules/文档位于packages/eslint-plugin/docs/rules/。3.1 jsx-import保证 css prop 可用的前置条件cssprop 在 React 环境中依赖jsx被正确设置为 pragma。该规则详见 jsx-import.md的判定与修复分两条路径经典 pragma 模式检查是否存在import { jsx } from emotion/react或emotion/core以及/** jsx jsx */注释。不满足时报错// 错误示例 let element div css{{ color: green }} /// 正确示例 /** jsx jsx */ import { jsx } from emotion/react let element div css{{ color: green }} /自动修复时会根据现状智能补全已有 jsx 导入就只补 pragma 注释已有 pragma 就在既有emotion/react导入中追加jsx两者皆无则同时插入注释与导入。另外该规则还识别context.settings.react.pragma配置settings: { react: { pragma: jsx } }。自动 runtime 模式对应 11.5.0 新增能力配置方式如下{ rules: { emotion/jsx-import: [error, { runtime: automatic, importSource: emotion/react }] } }该模式下规则不再要求显式导入而是检查jsxImportSource注释是否存在且指向正确缺失时自动插入。此外规则还会将css{...}内的裸模板字面量修复为css标签调用例如把div css{color:hotpink;} /改写为css标签包裹的形式。何时不使用如果你已通过 Babel 插件等方式自动添加导入与 pragma可关闭此规则。3.2 syntax-preference统一样式书写风格该规则详见 syntax-preference.md在string与object两种风格间强制二选一schema 定义见 syntax-preference.ts{ rules: { emotion/syntax-preference: [error, string] } }配置为string时以下对象写法会被报错提示Styles should be written using strings.const H1 styled.h1({ color: red }) const H1 styled(h1)({ color: red })配置为object时以下字符串写法会被报错const H1 styled.h1color: red; const H1 styled(h1)color: red;何时不使用如果你的团队不想把样式限定为单一语法可以不启用。3.3 pkg-renamingEmotion 11 迁移的包名 codemod这是 11.0.0 为 Emotion 11 迁移新增的规则README 中将其定位为 Emotion 11 codemod。它在 pkg-renaming.ts 中内置了一张包名映射表旧包名新包名emotion/coreemotion/reactemotionemotion/cssemotion/macroemotion/css/macroemotion/styled-baseemotion/styled/basejest-emotionemotion/jestbabel-plugin-emotionemotion/babel-plugineslint-plugin-emotionemotion/eslint-plugincreate-emotion-serveremotion/server/create-instancecreate-emotionemotion/css/create-instanceemotion-serveremotion/server命中映射的 import 声明会被报告renamePackage消息并可自动修复为import ... from 新包名。此外它还处理两类特殊场景默认导出迁移import css from emotion/css或/macro这类默认导入在 Emotion 11 中已改为具名导出规则会将其重写为import { css } from emotion/react保留局部别名emotion-theming 并入emotion-theming的导出已并入emotion/react规则会将导入源替换为emotion/react。启用方式{ rules: { emotion/pkg-renaming: error } }3.4 其余三条迁移辅助规则README 将以下三条规则归类为 Emotion 10 codemods并建议迁移后继续保留它们——例如让使用cssprop 时自动补全jsx导入等{ rules: { emotion/jsx-import: error, emotion/no-vanilla: error, emotion/import-from-emotion: error, emotion/styled-import: error } }styled-import见 styled-import.md检测import styled from react-emotion这类错误来源提示改为从emotion/styled导入import-from-emotion见 import-from-emotion.md在 Emotion 10 中react-emotion不再转发emotion的导出从react-emotion导入css等符号会被报错建议改用emotionno-vanilla见 no-vanilla.md在 React 场景下不推荐使用 vanilla 形态的emotion/css该规则对相关导入报错如果你不使用 React 而用 vanilla emotion应关闭此规则。注意README 特别提醒这些规则假设你正在使用 React如果不在 React 中使用应继续使用emotion包并相应调整规则策略。四、从 CHANGELOG 反推迁移实操综合 CHANGELOG 与源码可以整理出一条完整的 Emotion 10 → 11 迁移链改名先行按 11.0.0 的要求将plugins与规则前缀从emotion改为emotion开启 pkg-renaming codemod用emotion/pkg-renaming: error自动改写全部旧包名导入emotion/core→emotion/react、emotion→emotion/css等开启 Emotion 10 codemodsjsx-import、styled-import、import-from-emotion帮助清理react-emotion等历史导入no-vanilla约束 React 场景下的 vanilla 用法可按需永久关闭对齐现代 JSX runtime启用emotion/jsx-import的 automatic 模式后规则自动维护jsxImportSourcepragma无需手写统一风格用syntax-preference在全仓库范围内锁定字符串或对象风格。五、版本兼容速查版本关键变更意义11.12.0TypeScript 源码迁移空cssprop 崩溃修复类型声明自动生成规则健壮性提升11.11.0修复 Node ESM 导入工程兼容性11.10.0package.json 增加exports字段限制公开 API 范围11.7.0ESLint 8 加入 peer 依赖兼容 ESLint 6/7/811.5.0自动注入jsxImportSourcepragma支持 React 17 自动 runtime11.2.0syntax-preference支持css函数与参数检查风格检查覆盖面扩大11.0.0更名emotion/eslint-plugin新增pkg-renamingESLint 7 支持Emotion 11 迁移体系成型10.0.27补充 LICENSE合规10.0.14jsx-import自动修复并入已有 import自动修复体验优化六、结语从 10.0.14 的单一规则修补到 11.0.0 的改名与迁移体系再到 11.12.0 的 TypeScript 化与空cssprop 修复emotion/eslint-plugin的 CHANGELOG 本身就是一份 Emotion 生态演进的缩影。对于正在使用或计划迁移 Emotion 的团队开启这套规则不仅能借助自动修复节省大量手工改动还能在编码阶段持续守住样式导入与书写风格的规范。后续若需深入了解每条规则的边界行为可直接阅读仓库内 docs/rules 下的规则文档与src/rules/下的源码实现。【免费下载链接】emotion‍ CSS-in-JS library designed for high performance style composition项目地址: https://gitcode.com/gh_mirrors/em/emotion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考