vue-jsx-best-practices

vue-jsx-best-practices skill 概览

vue-jsx-best-practices skill 的核心价值，是帮你避开在 Vue 中编写 JSX 时最常见的一类错误：误以为 React 的 JSX 约定可以原样套用到 Vue。事实并非如此。在 Vue JSX 里，通常应使用标准 HTML 属性名，比如 class 和 for，而不是 React 风格的 className 与 htmlFor。

这个 skill 适合谁

这个 skill 特别适合以下前端开发者：

• 使用 JSX 或 TSX 编写 Vue 3 组件
• 正在把组件从 React 迁移到 Vue
• 遇到与 JSX props、attributes 相关的 TypeScript 报错
• 希望 Vue render function 与 Vue template 约定保持一致

如果你的任务是“把这段 Vue JSX 代码在不靠反复试错的情况下改到 type-safe 且写法地道”，那么 vue-jsx-best-practices 会很契合。

它真正帮你解决的是什么问题

它真正要解决的，不是“学习 JSX”这种宽泛目标，而是把粗糙的、混杂的、或带有明显 React 痕迹的 JSX，整理成符合 Vue 的 JSX 写法，并且做到：

• 能通过 TypeScript 检查
• 遵循 Vue 约定
• 避免迁移过程中那些隐蔽的 bug
• 对同时使用 template 和 render function 的团队来说也易读、易维护

vue-jsx-best-practices 的差异点在哪里

这个 skill 很聚焦，而这恰恰是它的实用之处。它不是试图覆盖 Vue 渲染相关的所有话题，而是专门盯住一个高频、容易踩坑的问题：Vue JSX 使用的是 HTML 属性名，而不是 React 的命名约定。也正因此，当你在排查错误属性、审查迁移代码、或统一整个代码库里的 TSX 写法时，它会特别有价值。

安装前你需要知道什么

这不是一份全面的 Vue 架构指南。仓库里的内容也很明确：这是一个紧凑型 skill，核心围绕一份参考文档 reference/render-function-jsx-vue-vs-react.md 展开。如果你想要的是针对 Vue JSX 语法差异和更稳妥迁移模式的定向指导，可以安装 vue-jsx-best-practices；如果你要找的是一整套完整的 JSX cookbook，它并不是为这个场景设计的。

如何使用 vue-jsx-best-practices skill

vue-jsx-best-practices 的安装使用场景

当你的 agent 或工作流需要生成、审查、或迁移 Vue JSX/TSX 代码时，就很适合用这个 skill。一个实用的安装命令是：

npx skills add vuejs-ai/skills --skill vue-jsx-best-practices

之后，当你的任务中出现类似以下表述时，就可以调用它：

• “convert this React component to Vue TSX”
• “fix JSX attribute type errors in Vue”
• “review this Vue render function for React-style conventions”
• “make this Vue JSX idiomatic”

先读这些仓库文件

这个 skill 体量不大，所以阅读顺序很关键，最快的路径是：

1. skills/vue-jsx-best-practices/SKILL.md
2. skills/vue-jsx-best-practices/reference/render-function-jsx-vue-vs-react.md

第二个文件承载了大部分实际价值。它解释了核心规则、TypeScript 为什么能抓到这类问题，以及迁移时具体应该改哪些地方。

这个 skill 需要什么样的输入

vue-jsx-best-practices 在你提供真实代码和上下文时效果最好，而不是只丢一句“帮我看看 Vue JSX”。建议至少提供：

• 组件源码
• 是否为 Vue 3
• 使用的是 JSX 还是 TSX
• 当前的 TypeScript 报错（如果有）
• 这段代码是否来自 React
• 你的构建工具，例如 Vite

最少可用输入示例：

• “This is a Vue 3 TSX component migrated from React. Fix invalid JSX attributes and explain each change.”

更好的输入示例：

• “Review this Vue 3 TSX file migrated from React. Replace React-only JSX conventions with Vue equivalents, preserve behavior, and note anything that will still require plugin or TypeScript config checks in Vite.”

这个 skill 重点帮助你落实的核心规则

最关键、最实用的结论其实很简单：

• 用 class，不要用 className
• 用 for，不要用 htmlFor
• 使用与 Vue template 对齐的 HTML 风格属性名
• 事件处理器使用标准的 on 前缀命名，例如 onClick

这点之所以重要，是因为 Vue runtime 有时可能比较宽松，但 TypeScript 理应把 React 风格的写法标出来。这反而是好事：问题能更早暴露，避免后续产生不一致。

如何把模糊需求写成高质量提示词

弱提示词：

• “Fix this JSX.”

强提示词：

• “Apply vue-jsx-best-practices to this Vue 3 TSX component. Identify any React JSX conventions such as className or htmlFor, replace them with Vue JSX equivalents, keep event handlers intact, and explain which changes are for type safety versus runtime behavior.”

为什么这个版本更好：

• 它明确指出了问题来自迁移场景
• 它要求给出具体替换项
• 它把编译期问题和 runtime 宽容行为区分开了
• 它减少了泛泛而谈的 Vue 建议

迁移任务推荐的 vue-jsx-best-practices 使用流程

一套比较稳妥的 vue-jsx-best-practices usage 流程是：

1. 粘贴原始的 React 组件或混合 JSX 组件。
2. 先让它做第一轮转换，统一成 Vue JSX 约定。
3. 再做第二轮，只关注 TypeScript 兼容性。
4. 逐行比对 props、labels 和事件绑定。
5. 在本地跑 type checker，把剩余报错继续反馈给这个 skill。

这种分阶段方式，通常比一开始就要求“完整迁移”更好，因为这个 skill 最擅长的是清理 JSX 约定问题，而不是替你完成整个框架级重写。

转换后的代码要重点检查什么

使用 vue-jsx-best-practices 后，建议重点检查：

• label 是否使用了 for
• CSS class 绑定是否使用了 class
• 是否保留了从 React 复制过来的 DOM prop 命名
• 事件处理器拼写是否正确
• 输出结果是否仍然暗含 React 组件模式

这个 skill 能帮你改进语法和约定，但像 hooks、state、组件 API 这类框架特有逻辑，仍然需要你自己验证。

TypeScript 与 Vite 相关注意事项

源资料明确提到，Vue JSX 的类型推断涉及 TypeScript 配置，同时 Vite 配置也属于相关上下文。实际使用时，这意味着你不能把 attribute 报错只当成“风格问题”。如果 TSX 环境配置正确，那么 React 风格的非法属性通常应该在类型检查阶段就暴露出来。若没有暴露，先别急着相信 runtime “看起来能跑” 的结果，应该先核对 Vue JSX plugin 和 TypeScript 配置是否正常。

适合与不适合的使用场景

适合：

• React 到 Vue 的 TSX 迁移
• Vue JSX 约定的代码审查
• 修复 Vue 3 中的 JSX attribute 报错
• 统一团队在 render function 中的编码风格

不适合：

• 从零学习 Vue
• 查询 template 语法
• 设计 Composition API 结构
• 处理超出 JSX 相关配置范围之外的完整构建问题排查

一个更容易拿到高质量输出的请求示例

你可以这样提：

“Use vue-jsx-best-practices on this Vue 3 TSX component. Flag every React-style JSX attribute, replace it with Vue JSX syntax, keep the component behavior unchanged, and give me a short checklist I can apply to the rest of the codebase.”

这种提示词的好处是：不仅能拿到修改结果，还能顺手得到一套可复用的审查清单。

vue-jsx-best-practices skill 常见问题

vue-jsx-best-practices 只适合 React 迁移吗？

不是。React 迁移确实是最典型、也最容易理解的使用场景，但如果你的团队本来就直接写 Vue TSX，并且希望统一约定、提高 type safety，这个 skill 同样有用。只要 Vue JSX 里混入了 React 风格属性名，它就能发挥作用。

vue-jsx-best-practices 会安装 plugin 或修改我的配置吗？

不会。这个 skill 提供的是指导，不是一个会自动修补 toolchain 的 package。你的应用仍然需要自行配置 Vue JSX 与 TypeScript 环境。它的作用，是帮助你识别在这些环境就绪后，代码应该写成什么样。

它和普通提示词相比，最大差别是什么？

普通提示词也许能生成“看起来像样”的 JSX，但不一定会严格遵守 Vue 特有的属性约定。vue-jsx-best-practices 在这个窄问题上更可靠，因为它把 Vue 与 React 在 JSX 上的错位，以及由此带来的类型安全影响，放在了最核心的位置。

这个 skill 对新手友好吗？

友好，前提是你已经了解基本的 Vue 或 JSX。它的范围足够聚焦，不会让人一下子面对太多概念。但如果你对 Vue 渲染方式完全陌生，它也不能替代组件、template 或 render function 的系统入门。

什么时候不该使用 vue-jsx-best-practices？

如果你的代码库只使用 Vue template，完全不用 JSX/TSX，那就没必要使用它。另一个应当跳过的场景是：你的问题根本和 JSX 属性命名无关，比如路由、状态管理，或者服务端渲染。

使用 React 风格属性时，runtime 一定会出问题吗？

不一定。参考文档提到，Vue runtime 有时比较宽松，会把某些属性正确转换。真正更大的问题在于一致性和类型安全：在 Vue JSX 里，TypeScript 理应拒绝这些 React 风格约定，而这通常正是你希望发生的事。

如何改进 vue-jsx-best-practices skill 的使用效果

把代码、报错和框架意图一起给出

想让 vue-jsx-best-practices 更快给出高质量结果，最好同时提供：

• 源组件代码
• 目标框架形态
• 真实的编译器或编辑器报错
• 当前目标是迁移、清理，还是 review

如果缺少这些信息，输出很可能只停留在显眼的属性替换上，漏掉周边更隐蔽的 JSX 假设。

要求它按 diff 思路做审查

一个高价值提示词是：

“Review this file using vue-jsx-best-practices. Do not rewrite everything. Only flag JSX conventions that are invalid, risky, or non-idiomatic in Vue, and explain each change briefly.”

这样可以减少过度改写，在已有代码库里也更容易做 review。

把语法修正和框架重写拆开

一个常见失败模式，是让这个 skill 同时处理 JSX 语法差异和完整的 React-to-Vue 行为迁移。更好的做法是把任务拆成三步：

1. 统一 JSX 约定
2. 修复类型错误
3. 重构框架逻辑

这样能让 vue-jsx-best-practices 聚焦在它真正擅长的部分。

让它输出一份可复用清单

仓库本身已经体现出 checklist 式任务思路。你可以进一步要求它产出一份团队可直接使用的审查清单，例如：

• 将 className 替换为 class
• 将 htmlFor 替换为 for
• 检查 on* 事件处理器
• 对转换后的文件重新运行 TS 检查

这样就能把一次性的帮助，沉淀成可重复执行的 review 流程。

第一轮完成后，继续验证配置前提

如果输出看起来没问题，但你的编辑器并没有标出错误属性，那就应该继续追问 TSX 环境的前提配置。这个 skill 明确提到 TypeScript 推断与 Vite config 是相关背景，所以如果本地验证链路太弱，真实错误就可能被掩盖。

使用后要警惕的常见失败模式

使用 vue-jsx-best-practices 后，建议重点留意这些问题：

• 嵌套元素里仍残留 React 属性名
• runtime “能跑”，但 TS 检查不过
• 迁移建议改动了行为，而不仅仅是语法
• labels、classes、DOM props 清理不彻底

这些都很适合再做一轮复查。

在第一轮输出后继续优化提示词

一个很强的二轮提示词是：

“Now do a second pass with vue-jsx-best-practices focused only on missed React-style JSX conventions and any Vue JSX typing issues. Keep logic unchanged.”

很多时候，这种跟进提示会比重新要求一次全新重写更有效。

以参考文件作为判断锚点

如果你不确定是否该相信输出结果，可以直接对照：

reference/render-function-jsx-vue-vs-react.md

这份文件最能体现这个 skill 的预期行为。对于安装决策来说，这也是一个积极信号：虽然 skill 很小，但它给出的指导足够具体，能切实减少那些本可避免的 Vue JSX 错误。