wevu-best-practices

wevu-best-practices

目的

wevu の制約を守りながら、Vue のような使いやすさでミニプログラムのランタイムロジックを実装します。ライフサイクルのタイミング、リアクティブな更新、コンポーネントの契約を明示します。

きっかけとなるシグナル

• ユーザーが wevu でページやコンポーネントのロジックを実装する方法を尋ねている。
• ユーザーがライフサイクルフックのタイミングやセットアップパターンについて尋ねている。
• ユーザーが props／emit の契約、イベントの detail ペイロード、双方向バインディングのパターンについて尋ねている。
• ユーザーがストアのアーキテクチャ、storeToRefs、型推論の動作について尋ねている。
• ユーザーが Vue 3 のウェブ版の動作とのランタイムの違いを報告している。

適用範囲

主な問題がランタイムの動作や状態／イベントの契約に関する場合に、このスキルを使用します。

次の場合は、主要なスキルとして使用しないでください。

• タスクがビルド／設定／サブパッケージ／CI のオーケストレーションに関するものです。weapp-vite-best-practices を使用してください。
• タスクの主な内容が .vue のマクロ／テンプレート構文の互換性です。weapp-vite-vue-sfc-best-practices を使用してください。
• タスクがネイティブのミニプログラムから段階的に移行するものです。native-to-weapp-vite-wevu-migration を使用してください。

クイックスタート

1. ランタイム API のインポートとコンポーネント登録の方式を確認します。
2. フックの登録タイミングとコンポーネント／ページの境界を確認します。
3. 状態／イベントのバインディングパターン（ref/reactive、emit、bindModel）を統一します。
4. 対象を絞ったランタイムテストまたはユニットテストで検証します。

実行手順

1. ランタイムの規約を確立する

• ランタイム API は wevu からのみインポートします。
• ページとコンポーネントの両方で defineComponent による登録を使用します。
• オプション形式の data を使用する場合は、関数として定義します。

2. 境界とタイミングを検証する

• ページフックはページのコンテキスト内でのみ使用します。
• ライフサイクルフックは setup() 内で同期的に登録します。
• await の後にフックを登録しないでください。

3. リアクティブな更新パターンを統一する

• 状態の導出には ref/reactive/computed を優先します。
• 不透明で大規模な状態の書き込みを避け、粒度の細かいリアクティブな更新を優先します。
• フォームやイベントの意味づけが単純でない場合は、明示的なバインディングを使用します。

4. イベントと双方向バインディングの契約を定義する

• ミニプログラムの仕様に従い、ctx.emit(event, detail, options) を使用します。
• 再利用可能なフィールドの契約には、bindModel／useBindModel を優先します。
• 値の変換を行う場合は、パーサー／フォーマッターの動作を記述します。

5. ストアの運用規律を適用する

• シンプルなドメインと強力な TS 型推論には、Setup Store を優先します。
• 状態／ゲッターを分割代入する場合は、storeToRefs を使用します。
• グローバルなプラグイン／永続化の動作が必要な場合に限り、createStore() を導入します。

6. 互換性を明示的に検証する

• ランタイムのビジネスロジックでは、DOM／ブラウザー専用 API を使用しないでください。
• Node／Vitest でブリッジのテストを行う場合は、Component／wx をスタブ化します。
• プラットフォームの違いは、暗黙のバグではなく明示的な制約として扱います。

制約

• setup() 内で await の後にフックを登録しないでください。
• ストアでは storeToRefs を使わずに状態を直接分割代入しないでください。
• テンプレートやライフサイクルのタイミングで、文書化されていない Vue ウェブ版専用の動作に依存しないでください。
• シリアライズできないネイティブインスタンスオブジェクトをテンプレートの状態として返さないでください。

出力要件

このスキルを適用する場合、次を提示します。

• ランタイムのリスク概要（ライフサイクル／状態／イベント／ストア）。
• ファイル単位の具体的な編集内容。
• Vue 3 ウェブ版のランタイムとの互換性に関する注意点。
• 最小限の検証コマンドと、期待される結果。

完了チェック

• ビジネスコードの API は vue ではなく wevu からインポートされています。
• ページ／コンポーネントの境界で一貫した使い方がされています。
• フックの登録は同期的で、予測可能なタイミングで行われています。
• ストアはシングルトンと storeToRefs の規約に従っています。
• テンプレート／イベントのバインディングは、ミニプログラムでサポートされる仕様に合致しています。

参考資料

• references/component-patterns.md
• references/store-patterns.md
• references/troubleshooting-checks.md