vue-jsx-best-practices

vue-jsx-best-practices 技能總覽

vue-jsx-best-practices 這個技能，專門幫你避開在 Vue 撰寫 JSX 時最常見的錯誤：以為 React 的 JSX 慣例可以原封不動套用到 Vue。其實不行。在 Vue JSX 裡，一般應該使用標準 HTML 屬性名稱，例如 class 和 for，而不是 React 風格的 className 和 htmlFor。

這個技能適合誰

這個技能特別適合以下前端開發者：

• 使用 JSX 或 TSX 撰寫 Vue 3 元件
• 正在把元件從 React 遷移到 Vue
• 在 JSX props 或 attribute 上遇到 TypeScript 錯誤
• 希望 Vue render function 能和 Vue template 慣例一致

如果你的工作目標是「在不靠反覆試錯的情況下，讓這段 Vue JSX 程式碼型別安全、寫法也夠道地」，那麼 vue-jsx-best-practices 會非常適合。

它實際能幫你完成什麼工作

這個技能真正解決的，不是泛泛地「學 JSX」，而是把寫得粗糙、混雜，或帶有 React 味道的 JSX，轉成符合 Vue 的 JSX，讓它：

• 通過 TypeScript 檢查
• 遵循 Vue 慣例
• 避免遷移時那種不容易發現的 bug
• 對同時使用 templates 與 render functions 的團隊來說仍然容易閱讀

vue-jsx-best-practices 有什麼不同

這個技能的範圍很窄，而這正是它的價值所在。它不是想把所有 Vue rendering 主題一網打盡，而是專注在一個很常卡人的細節：Vue JSX 使用的是 HTML attribute 名稱，不是 React 那套命名方式。這讓它在你除錯錯誤屬性、審查遷移後的程式碼，或統一整個 codebase 的 TSX 寫法時特別有用。

安裝前你該先知道什麼

這不是一份完整的 Vue 架構指南。從 repository 內容來看，這是一個相當精簡的技能，核心圍繞在一份參考文件：reference/render-function-jsx-vue-vs-react.md。如果你要的是 Vue JSX 語法差異與更安全的遷移模式的精準指引，而不是一本完整的 JSX cookbook，那就適合安裝 vue-jsx-best-practices。

如何使用 vue-jsx-best-practices 技能

vue-jsx-best-practices 的安裝情境

當你的 agent 或工作流程要產生、審查，或遷移 Vue JSX/TSX 時，就很適合用這個技能。實際可用的安裝指令如下：

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

之後，當你的任務裡出現這類需求時就可以呼叫它：

• 「把這個 React component 轉成 Vue TSX」
• 「修正 Vue 裡 JSX attribute 的 type errors」
• 「幫我檢查這個 Vue render function 有沒有 React 風格慣例」
• 「把這段 Vue JSX 改得更符合慣例」

先讀這些 repository 檔案

這個技能很小，所以閱讀順序很重要。最快的讀法是：

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

第二個檔案承載了大部分實際價值。它會說明核心規則、TypeScript 為什麼會抓到這類問題，以及遷移時具體該改哪些地方。

這個技能需要什麼輸入

vue-jsx-best-practices 在你提供實際程式碼與上下文時效果最好，不要只丟一句「幫我處理 Vue JSX」。建議至少包含：

• 元件原始碼
• 是否為 Vue 3
• 你使用的是 JSX 還是 TSX
• 目前的 TypeScript 錯誤（如果有）
• 這段程式碼是否來自 React
• 你的 build tool，例如 Vite

最低可用輸入：

• 「這是一個從 React 遷移過來的 Vue 3 TSX component。請修正無效的 JSX attributes，並說明每一項修改。」

更好的輸入：

• 「請審查這個從 React 遷移過來的 Vue 3 TSX 檔案。把只屬於 React 的 JSX 慣例替換成 Vue 對應寫法，保留原本行為，並指出哪些地方仍需要在 Vite 的 plugin 或 TypeScript 設定上進一步確認。」

這個技能協助你落實的核心規則

最重要的實務結論其實很簡單：

• 用 class，不要用 className
• 用 for，不要用 htmlFor
• 使用和 Vue templates 對齊的 HTML 風格 attribute 名稱
• 事件處理器使用標準的 on 前綴命名，例如 onClick

這一點很重要，因為 Vue runtime 有時可能比較寬鬆，但 TypeScript 理應會把 React 風格寫法標示出來。這反而是好事：你能更早發現不一致。

把模糊需求改寫成更強的 prompt

弱的 prompt：

• 「幫我修這段 JSX。」

強的 prompt：

• 「請對這個 Vue 3 TSX component 套用 vue-jsx-best-practices。找出任何 React JSX 慣例，例如 className 或 htmlFor，改成 Vue JSX 對應寫法，保留 event handlers，並說明哪些修改是為了型別安全、哪些只是 runtime 行為上的差異。」

為什麼這樣比較好：

• 它明確指出問題來自遷移脈絡
• 它要求具體替換，不只是泛泛建議
• 它把 compile-time 問題和 runtime 寬容行為區分開來
• 它能減少模型輸出一堆籠統的 Vue 建議

遷移任務建議工作流程

一個好的 vue-jsx-best-practices usage 工作流程如下：

1. 貼上原本的 React 或混合式 JSX component。
2. 先要求做第一輪轉換，改成 Vue JSX 慣例。
3. 再要求第二輪，只聚焦在 TypeScript 相容性。
4. 逐行比對 props、labels 與 event bindings。
5. 在本地跑 type checker，把剩下的錯誤再丟回技能處理。

這種分階段做法，比一次要求「完整遷移」更有效，因為這個技能最強的是 JSX 慣例清理，不是整個 framework 的全面重寫。

檢查轉換後程式碼時要看什麼

使用 vue-jsx-best-practices 後，建議檢查：

• label 是否使用 for
• CSS class 綁定是否改成 class
• 是否還殘留從 React 複製過來的 DOM prop 命名
• event handler 拼法是否正確
• 輸出結果是否仍然偷偷沿用 React component 模式

這個技能可以幫你改善語法與慣例，但像是 hooks、state、component APIs 這類 framework 專屬邏輯，還是要你自己再驗證。

TypeScript 與 Vite 注意事項

原始資料有明確提到，Vue JSX 型別推斷的 TypeScript 設定，以及 Vite 設定，都是相關主題。實務上這代表你不該把 attribute 錯誤只當成風格問題。如果你的 TSX 環境設得正確，React 風格的錯誤 attribute 應該會在 type checking 時浮現。如果沒有出現，先確認你的 Vue JSX plugin 與 TypeScript 設定，再決定要不要相信那個「看起來能跑」的 runtime 結果。

最適合與不適合的使用情境

最適合：

• React 到 Vue 的 TSX 遷移
• Vue JSX 慣例的 code review
• 修正 Vue 3 裡的 JSX attribute 錯誤
• 統一團隊在 render functions 中的風格

不適合：

• 從零學 Vue
• 查 template 語法
• Composition API 設計
• 超出 JSX 相關設定範圍的完整 build setup 除錯

能得到更好輸出的範例請求

你可以這樣問：

「請對這個 Vue 3 TSX component 使用 vue-jsx-best-practices。標出每一個 React 風格的 JSX attribute，替換成 Vue JSX 語法，保持元件行為不變，並給我一份可套用到整個 codebase 的簡短檢查清單。」

這類 prompt 通常不只會得到修正結果，也會產出可重複使用的審查模式。

vue-jsx-best-practices 技能 FAQ

vue-jsx-best-practices 只適合 React 遷移嗎？

不是。React 遷移是最明確的使用案例，但如果你的團隊本來就直接寫 Vue TSX，又想維持一致且型別安全的慣例，這個技能同樣有用。只要 Vue JSX 裡混入了 React 風格 attribute 名稱，它就派得上用場。

vue-jsx-best-practices 會安裝 plugin 或修改我的設定嗎？

不會。這個技能提供的是指引，不是一個會自動修補 toolchain 的 package。你的 app 仍然需要自己完成 Vue JSX 與 TypeScript 環境設定。這個技能主要幫你判斷：在那些設定都到位之後，程式碼應該長什麼樣子。

它和一般 prompt 最大差異是什麼？

一般 prompt 可能會產生「看起來像 JSX」的內容，但不一定真的遵守 Vue 專屬的 attribute 慣例。vue-jsx-best-practices 在這個狹窄問題上更可靠，因為它聚焦的是 Vue 與 React 之間 JSX 寫法不相容的地方，以及這些差異對型別安全的影響。

這個技能對新手友善嗎？

算是友善，前提是你已經懂基本的 Vue 或 JSX。因為它的範圍夠窄，所以不會太難上手。但如果你對 Vue rendering 完全陌生，這個技能仍然不能取代更完整的元件、templates 或 render functions 入門教學。

什麼情況下不該用 vue-jsx-best-practices？

如果你的 codebase 完全使用 Vue templates、沒有用到 JSX/TSX，就可以跳過。若你的問題和 JSX attribute 命名無關，例如 routing、state management 或 server rendering，也不適合靠這個技能解決。

如果我用了 React 風格 attribute，runtime 一定會壞掉嗎？

不一定。參考文件有提到，Vue runtime 有時會相當寬鬆，某些 attribute 甚至還是會被正確轉換。真正更大的問題在於一致性與型別安全：在 Vue JSX 裡，TypeScript 理應拒絕這些 React 慣例，而這通常正是你想要的結果。

如何進一步提升 vue-jsx-best-practices 技能使用效果

一次提供程式碼、錯誤訊息與 framework 目標

想讓 vue-jsx-best-practices 更快給出高品質結果，最有效的方式是一起提供：

• 原始 component
• 目標 framework 形式
• 真實的 compiler 或 editor 錯誤
• 這次目標是 migration、cleanup 還是 review

少了這些資訊，輸出很可能只停留在表面上的 attribute 替換，而忽略周邊 JSX 假設。

要求以 diff 為導向的審查

一個高價值 prompt 是：

「請用 vue-jsx-best-practices 審查這個檔案。不要全部重寫，只標出在 Vue 中無效、有風險或不夠慣用的 JSX 慣例，並簡短說明每一項修改。」

這樣可以減少過度修改，也更適合既有 codebase 的 review 流程。

把語法修正和 framework 重寫拆開

常見失敗模式之一，是要求技能同時解決 JSX 語法差異，以及完整的 React-to-Vue 行為遷移。想提高輸出品質，最好把任務拆成：

1. 正規化 JSX 慣例
2. 修正型別錯誤
3. 重構 framework 邏輯

這樣能讓 vue-jsx-best-practices 專注在它真正擅長的範圍。

要求產出可重複使用的檢查清單

repository 本身就帶有 checklist 式任務思維。你可以進一步要求技能產出適合團隊使用的審核清單，例如：

• 把 className 改成 class
• 把 htmlFor 改成 for
• 檢查 on* event handlers
• 對轉換後檔案重新執行 TS 檢查

這能把一次性的協助，轉成可持續重複執行的 review 流程。

第一輪後要驗證設定前提

如果輸出看起來都正確，但你的 editor 沒有把錯誤 attribute 標示出來，建議接著追問 TSX 環境的前提假設。這個技能有提到 TypeScript inference 與 Vite config 都是相關脈絡，所以如果你的本地設定驗證太弱，真正的錯誤就可能被掩蓋掉。

常見失敗模式要留意

使用 vue-jsx-best-practices 後，請特別注意這些問題：

• 巢狀元素裡仍殘留 React attribute 名稱
• runtime 看似可用，但 TS 檢查仍然失敗
• 遷移建議動到了行為，而不只是語法
• labels、classes 與 DOM props 沒有清乾淨

這些都很適合再做第二輪審查。

看完第一版輸出後再優化 prompt

一個很實用的迭代 prompt 是：

「現在請用 vue-jsx-best-practices 再做第二輪，只檢查遺漏的 React 風格 JSX 慣例，以及任何 Vue JSX typing 問題。不要改動邏輯。」

這種 follow-up 往往比要求它整份重新改寫更有效。

以參考檔案作為判斷依據

如果你不確定要不要相信輸出結果，可以對照：

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

這個檔案是理解此技能預期行為最清楚的依據。從安裝判斷角度來看，這也是一個好訊號：雖然技能本身很精簡，但它的指引足夠具體，能實際減少可避免的 Vue JSX 錯誤。