weapp-vite-react-best-practices

weapp-vite React のベストプラクティス

用途

WeChat ミニプログラムで、予測可能な React 19 のコンパイル、レンダリング、コンポーネント相互運用の境界を確立し、実際のビルドとランタイムのシグナルで結果を検証します。

適用しない場面

• 汎用ビルド、分割パッケージ、マルチプラットフォーム、CLI：weapp-vite-best-practices を使用します。
• Wevu JSX/TSX または Vue SFC：それぞれ wevu-best-practices、weapp-vite-vue-sfc-best-practices を使用します。
• ネイティブプロジェクトから Wevu/Vue SFC への段階的な移行：native-to-weapp-vite-wevu-migration を使用します。
• Alipay、Douyin などの WeChat 以外のターゲット：現時点では React ランタイムの互換性は保証されていません。

基本的な手順

1. 現在のワークスペースで、React 19.3.x、react-reconciler 0.34.x、@weapp-vite/react の組み合わせを検証します。react-dom は導入しないでください。
2. プロジェクトレベルの weapp.react で React owner を有効にします。同一ビルド内の .jsx / .tsx はすべて React コンパイルチェーンに属するものとし、Wevu JSX と混在させないでください。
3. auto をベースラインとして設定します。安定した構造はネイティブ WXML/binding slots を生成し、静的に証明できず bridge も含まない構造は dynamic tree に入ります。
4. ページのネイティブエントリーポイントで root の作成、ホストイベントの転送、アンマウントを行います。React ビューは隣接する TSX モジュールに配置し、Page のライフサイクルをコンポーネントツリーに隠さないでください。
5. ネイティブまたは Wevu カスタムコンポーネントが必要な場合は、まず JSON の usingComponents に登録し、現在の TSX のトップレベルで文字列リテラルを使って createNativeComponent を呼び出します。
6. React ベースのミニプログラムコンポーネントでデフォルトスロットが必要な場合は Slot を使用します。scoped slot、model、動的 tag がサポートされているとは想定しないでください。
7. React Compiler はデフォルトで無効のままにします。@swc/core をインストールし、fallback warning、sourcemap、実行時の動作を検証する準備ができている場合にのみ有効にしてください。
8. 「ランタイムの単体テスト -> weapp-vite のコンパイルテスト -> ビルド e2e -> DevTools ランタイム」の順に、段階ごとに検証します。
9. WebView glass-easel はデフォルトで無効のままにします。開発者ツールと実機の基本ライブラリがどちらも 3.8.12 以上の場合に限り、ユーザーがホスト JSON で componentFramework と glassEaselWebview をセットで設定し、wv analyze --glass-easel-check で static/dynamic WXML と SelectorQuery を検査します。React の静的テンプレートでは、共有 WXML エンティティのエスケープ規約を引き続き使用します。

重要な境界

• renderMode: 'dynamic' は reconciler tree の調査に使用します。ネイティブコンポーネント bridge はサポートしていません。
• renderMode: 'static' で静的に証明できない構造に遭遇した場合は、意味を黙って失うのではなく、ただちに失敗させる必要があります。
• auto では、bridge を条件分岐やリストなどの動的な構造に含めてはならず、ファイルをまたぐ bridge 宣言もサポートされません。
• onValueChange は bind:value-change に、onValueChangeCapture は capture-bind:value-change にマッピングされます。
• React プロジェクトでは .vue のコンパイルに wevu を明示的にインストールできますが、TSX は引き続き React owner に属します。相互運用はミニプログラムのカスタムコンポーネント bridge を介して行います。

出力

この skill を適用する際、出力には次の内容を含める必要があります。

• React owner、render mode、プラットフォーム境界の診断。
• ページ root のライフサイクルと TSX のファイル単位の変更に関する提案。
• ネイティブ/Wevu bridge の登録とイベント規約の確認。
• 最小限の検証コマンドと、実際の DevTools での確認が必要な動作。

完了条件

• React の依存関係の組み合わせと weapp.react の設定が明確です。
• ページのアンロード時に root が正しく unmount され、ホストイベントを転送できます。
• bridge tag が usingComponents と一致し、現在サポートされていない動的構造は使用されていません。
• Compiler の fallback、ビルド成果物、実際のランタイムシグナルが、それぞれ区別して検証されています。

参考資料

• 設定、render mode、Compiler：references/config-and-render-modes.md
• ネイティブ/Wevu の相互運用：references/component-interop.md
• 検証の段階：references/validation-matrix.md