vue-pinia-best-practices

vue-pinia-best-practices 技能總覽

vue-pinia-best-practices 是一個聚焦型的指導技能，適合使用 Pinia 的 Vue 3 團隊，用來降低狀態管理 bug，並在架構預設上做出更穩妥的決策。它不是泛用的 Vue 教學；相反地，它專注在真實專案裡最常浪費時間的 Pinia 問題：安裝時機不對、因解構造成 reactivity 失效、setup store 在 SSR/DevTools 上的問題，以及哪些狀態應該放進 store、哪些其實應該放在 URL 的判斷。

這個技能最適合哪些人

vue-pinia-best-practices 很適合：

• 已經在使用或正準備導入 Pinia 的 Vue 3 開發者
• 從 Vuex 或自行用 reactive() 寫的 store 遷移中的團隊
• 遇到像 getActivePinia() 這類特定執行期問題的開發者
• 想建立可擴展、而不是只適合小型 demo 的前端工程師

如果你的應用程式有共享狀態、路由、SSR、DevTools 檢查流程，或有多位協作者共同維護，這個技能會特別有價值。

它能幫你完成什麼工作

當你希望 AI 助手在審查或產生 Pinia 程式碼時，能少踩一些隱藏陷阱，就很適合用 vue-pinia-best-practices。真正要完成的工作不是「解釋 Pinia 是什麼」，而是「幫我把 store 結構設計正確，並在上線前先避開已知錯誤」。

它和一般 Vue 提示詞有什麼不同

一般提示詞可能會產出看起來合理、但實際跑起來仍會出錯的 Pinia 程式碼。vue-pinia-best-practices 更強的原因，在於它圍繞少數幾個高影響、且有明確依據的模式：

• 在任何會使用 store 的程式碼之前先安裝 Pinia
• 避免在 app 初始化前於頂層直接存取 store
• setup store 必須回傳所有 reactive state
• 解構 state 與 getters 時要用 storeToRefs()
• 可分享的篩選條件狀態應放在 URL，而不只是 Pinia
• 較大的應用程式應優先選用 Pinia，而不是臨時拼湊的 store

它不打算涵蓋哪些內容

這個技能刻意維持範圍精簡，不會取代下列完整文件：

• 進階 plugin 撰寫
• 端對端 SSR 框架整合細節
• 所有可能的 store 組織風格
• 與 Pinia 無關的 Vue 元件模式

如果你需要非常完整、而且高度依賴特定框架的設定方式，請把這個技能當成防呆與守門層，而不是完整的實作方案。

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

vue-pinia-best-practices 的安裝脈絡

如果你的 skill runner 支援以 repository 為基礎安裝技能，就像加入同一套集合中的其他技能一樣，從 vuejs-ai/skills 加入 vue-pinia-best-practices。安裝後，最重要的工作目錄是：

• skills/vue-pinia-best-practices/

建議先從這個檔案開始：

• SKILL.md

接著再依照你目前遇到的問題，閱讀對應的參考檔案。

依問題類型優先閱讀這些檔案

最快的方式，是直接打開和你症狀相符的參考檔：

• reference/pinia-no-active-pinia-error.md：啟動／安裝順序造成的 crash
• reference/pinia-setup-store-return-all-state.md：setup store 在 SSR 或 DevTools 上的問題
• reference/pinia-store-destructuring-breaks-reactivity.md：解構後 UI 不再更新
• reference/state-url-for-ephemeral-filters.md：filters、search、sort、pagination 這類狀態
• reference/state-use-pinia-for-large-apps.md：架構層級的判斷
• reference/store-method-binding-parentheses.md：非 Pinia 的 reactive store 中方法綁定問題

這個 repo 內容不大，所以比起從頭到尾照順序讀，更重要的是一開始就找對檔案。

要讓技能發揮效果，你應提供哪些輸入

vue-pinia-best-practices 在你提供具體實作情境時效果最好，而不是只說一句「幫我處理 Pinia」。建議提供：

• 你的 Vue 版本，以及是否使用 Vue 3 + Composition API
• 這個 store 是 Pinia store，還是自行手寫的 reactive store
• 問題出現在啟動時、導頁時、template 中，還是重新整理後
• 相關檔案，例如 main.ts、router 設定、一個 store 檔，以及一個使用它的 component
• SSR、DevTools 可見性或 URL 持久化是否重要

如果缺少這些背景，助理可能會給出 technically 正確、但和你實際情境不對位的建議。

把模糊需求改寫成高品質提示詞

弱提示詞：

• 「Help me fix my Pinia store.」

更好的寫法：

• 「Use the vue-pinia-best-practices skill. I have a Vue 3 app with Pinia and Vue Router. I get getActivePinia() during startup when a router guard reads useAuthStore(). Review my main.ts and router file, explain the root cause, and rewrite the setup in the safest order.」

另一個強而有力的例子：

• 「Use vue-pinia-best-practices to review this setup store for SSR and DevTools compatibility. Tell me if any reactive state is not returned, what that breaks, and provide a corrected store.」

vue-pinia-best-practices 的實用使用流程

使用這個技能時，較可靠的流程如下：

1. 先辨識症狀類型：啟動、reactivity、setup store 結構、URL 狀態，或架構問題。
2. 附上能重現問題的最小檔案集合。
3. 要求助理根據對應的 reference/*.md 檔案進行診斷。
4. 請它提供修正後的程式碼版本，以及一條之後可重複套用的簡短規則。
5. 第一次修正後，再要求一份 checklist，把同一模式套用到整個 repo。

這通常比起在沒有程式碼的情況下，直接要求一次性的「best practices review」更有效。

用它排查啟動與 plugin 順序 bug

vue-pinia-best-practices 最有價值的用途之一，就是處理「no active Pinia」這類錯誤。如果 router guard 或某些模組太早呼叫 store，請要求助理檢查：

• main.js 或 main.ts
• router 建立方式與 guard 註冊順序
• 任何在頂層 import 後就直接呼叫 useXxxStore() 的程式碼

關鍵問題通常是初始化時機，而不一定是 store 實作本身。

用它檢查解構是否破壞 reactivity

如果你從 store 取值之後 UI 就不再更新，請讓技能檢查你是不是直接把 store 解構了。常見的修正方式是：

• actions 若有需要，可以直接解構
• state 與 getters 則改用 storeToRefs()

對任何會大量讀取 store 值的 component，這都是非常值得做的 review 題目。

用它檢查 setup store 的 SSR 與 DevTools 相容性

如果你使用 defineStore('x', () => {})，請讓助理確認所有 reactive state 是否都有被回傳。這很重要，因為漏回傳的 state 可能會悄悄導致：

• SSR serialization 與 hydration 失效
• Vue DevTools 無法正確檢查
• Pinia plugin 相容性出問題

這也是為什麼 vue-pinia-best-practices 很適合放在 code review 階段使用，而不是等到除錯時才拿出來。

用它判斷狀態應該放在哪裡

vue-pinia-best-practices guide 一個比較細膩、但很實用的用法，是協助判斷某筆資料到底該不該放進 Pinia。你可以要求助理把狀態分類成：

• app 層級的共享狀態
• 元件本地狀態
• 應由 URL 承載的畫面狀態，例如 filters、search、pagination、sorting

這類情境下，這個技能比一般 Pinia 程式碼片段更有價值，因為它能在程式越長越大之前，先避免你走錯架構方向。

最適合 repo 審查的提示詞模式

如果你要把 vue-pinia-best-practices for Frontend Development 用於 repo 稽核，推薦這種審查提示詞：

• 「Use the vue-pinia-best-practices skill to audit these files for Pinia gotchas. For each issue, label it as install timing, reactivity, setup-store return shape, or state-placement mistake. Show exact fixes and explain production impact.」

這樣的 framing 能讓模型更傾向輸出可執行的發現，而不是停留在抽象建議。

vue-pinia-best-practices 技能常見問題

vue-pinia-best-practices 適合初學者嗎？

適合，只要你已經在用 Vue 3 開發，而且開始接觸 Pinia。這個技能篇幅精簡、以問題為中心，通常比大範圍文件更容易直接套用。不過，如果你是完全新手，對 stores、getters、actions 等基本概念還不熟，仍然可能需要先看官方 Pinia 基礎教學。

vue-pinia-best-practices 最擅長處理哪些問題？

它最擅長的是少數幾類常見但影響很大的問題：

• getActivePinia() 的設定／初始化時機錯誤
• 直接解構導致的 reactivity 失效
• setup store 沒有回傳完整 state
• 判斷何時該用 URL query state，而不是 store state
• 判斷在什麼情況下 Pinia 比手寫狀態更值得採用

這會比直接問一般 Pinia 問題更好嗎？

通常在這些主題上會更好。一般提示詞常會產出看似正確的程式碼，但忽略 plugin 順序、SSR serialization 或 storeToRefs() 這些執行期細節。vue-pinia-best-practices skill 則把模型聚焦在已被驗證的常見陷阱與修正方式上。

什麼時候不該用 vue-pinia-best-practices？

如果你的任務主要是以下內容，就不太適合：

• 從零開始學 Vue
• 與 Pinia 無關、偏框架部署設定的問題
• 超出這個 repo 範圍的進階狀態機設計
• 非 Vue 的前端技術棧

它是面向 Pinia 的防呆與守門技能，不是萬用型前端架構技能。

它能幫助 Vuex 遷移決策嗎？

可以，雖然是間接的。repo 明確支持一個觀點：對較大的 Vue 應用來說，Pinia 是更合理的預設選擇，而 Vuex 已進入 maintenance mode。當你想把過去的 Vuex 習慣重整成現在的 Pinia 寫法時，它特別有用，尤其是在較簡潔的 store 使用方式與 tooling 上。

vue-pinia-best-practices 也能幫忙看手寫 store 嗎？

部分可以。有一份參考檔專門處理 reactive store 的 method-binding 陷阱，這個技能也能協助你判斷手寫狀態是否仍然合理。不過它的核心重心還是 Pinia，而不是自訂 store library。

如何提升 vue-pinia-best-practices 技能的使用效果

提供精確的失敗症狀

如果想讓 vue-pinia-best-practices 輸出品質更好，請提供精確錯誤訊息、出現位置，以及問題從什麼時候開始。例如：

• 「Error occurs only during router navigation」
• 「DevTools does not show a ref from my setup store」
• 「UI stops updating after destructuring the store in <script setup>」

這些線索都能直接對應到 repo 最擅長處理的問題。

補上生命週期與檔案邊界資訊

很多 Pinia bug，本質上其實是時機問題。請告訴助理這段程式碼是在哪個階段執行：

• 在 module import 時
• 在 setup() 中
• 在 router guard 中
• 在 app bootstrap 期間
• 在 SSR hydration 期間

這些背景能幫助技能分辨：到底是安裝順序問題，還是一般元件邏輯 bug。

提供最小但完整的程式碼切片

通常更好的輸入會包含：

• main.ts
• 若 guards 會使用 store，附上一個 router 檔
• 一個 store 檔
• 一個消費該 store 的 component

不要一開始就把整個 repo 全貼上來。聚焦且可重現的範例，能加快診斷速度，也能減少空泛的制式建議。

不只要修正，也要求分類

一個高產出的提示詞是：

• 「Classify each issue by category, explain why it happens, then patch the code.」

對這個技能來說，好的分類包括：

• install timing
• reactivity
• setup-store return shape
• URL vs store state
• scale/architecture fit

這能讓輸出結果更容易在之後的其他檔案中重複利用。

要求提供修正前後的程式碼

比起 vue-pinia-best-practices install 本身，其實真正的採用關鍵是：它能不能實際改善你產生出的程式碼？最好的判斷方式，就是要求它提供：

• 修正後的程式碼範例
• 原始寫法失敗原因的簡短說明
• 可套用到其他地方的 checklist

這樣一來，這個技能就不只是一次性回答，而會變成可重複使用的 review 工具。

留意常見的失敗模式

當輸入資訊不足時，最容易出現品質不佳的輸出。例如：

• 只說要「best practices」，卻沒有任何程式碼或症狀
• 沒有說明 store 是 option-style 還是 setup-style
• 啟動相關問題卻沒附 router 設定
• 描述 filter persistence 需求時，沒有提到 URL 可分享性

這些情況下，助理可能會給你正確但無法解決問題的建議。

第一次輸出後要再追問一輪

收到第一輪回答後，建議再追問第二輪，例如：

• 「Now scan for the same pattern in the rest of my stores.」
• 「Convert this fix into a team convention.」
• 「Show how this changes if the state should be shareable by URL.」
• 「Add SSR and DevTools checks to the review.」

這是從 vue-pinia-best-practices usage 拿到比單次修正更多價值的最簡單方式。

把 reference 檔轉成 review 規則

這些 reference 檔都很精簡，很適合直接轉成團隊 code review 檢查項目。例如：

• 不要在 module top level 呼叫 useXxxStore()
• 如果 guards 會讀 store，先安裝 Pinia 再安裝 router
• setup store 必須回傳所有 reactive state
• 解構 state/getter 時要用 storeToRefs()
• 如果需要重新整理後保留或可分享，view filters 應放在 URL

想長期提升 vue-pinia-best-practices for Frontend Development 的成效，最佳做法不是只拿它來補 bug，而是把它變成你團隊預設規範的一部分，在問題出現之前就先把關。