React Hook Form ベストプラクティス

React Hook Form アプリケーションの包括的なパフォーマンス最適化ガイド。8つのカテゴリーにわたる41のルールを含み、フォーム開発、自動リファクタリング、コード生成のガイドとなるよう影響度別に優先順位付けされています。

適用時期

以下の場合に、これらのガイドラインを参照してください：

• React Hook Form で新しいフォームを作成する場合
• useForm オプション (mode、defaultValues、validation) を設定する場合
• watch/useWatch でフォーム値に購読する場合
• 制御されたUIコンポーネント (MUI、shadcn、Ant Design) を統合する場合
• useFieldArray で動的フィールド配列を管理する場合
• フォームのパフォーマンス問題をレビューする場合

ルールカテゴリー優先度順

優先度	カテゴリー	影響度	プレフィックス
1	フォーム設定	重大	formcfg-
2	フィールド購読	重大	sub-
3	制御コンポーネント	高	ctrl-
4	検証パターン	高	valid-
5	フィールド配列	中～高	array-
6	状態管理	中	formstate-
7	統合パターン	中	integ-
8	高度なパターン	低	adv-

クイックリファレンス

1. フォーム設定 (重大)

• formcfg-validation-mode - 最適なパフォーマンスのため onSubmit モードを使用
• formcfg-revalidate-mode - 送信後のパフォーマンスのため reValidateMode を onBlur に設定
• formcfg-default-values - フォーム初期化のため常に defaultValues を提供
• formcfg-async-default-values - サーバーデータに非同期 defaultValues を使用
• formcfg-should-unregister - 動的フォームのメモリ効率のため shouldUnregister を有効化
• formcfg-useeffect-dependency - useEffect 依存配列で useForm の戻り値を避ける

2. フィールド購読 (重大)

• sub-usewatch-over-watch - 隔離された再レンダーのため useWatch を watch の代わりに使用
• sub-watch-specific-fields - フォーム全体ではなく特定フィールドを購読
• sub-usewatch-with-getvalues - タイミング安全性のため useWatch と getValues を組み合わせ
• sub-deep-subscription - データが必要なコンポーネントツリーの深い場所で購読
• sub-avoid-watch-in-render - 1回限りの読み取りのためレンダー内での watch() 呼び出しを避ける
• sub-usewatch-default-value - 初期レンダーのため useWatch に defaultValue を提供
• sub-useformcontext-sparingly - 深いネストのため useFormContext を慎重に使用

3. 制御コンポーネント (高)

• ctrl-usecontroller-isolation - 再レンダー隔離のため useController を使用
• ctrl-avoid-double-registration - useController での二重登録を避ける
• ctrl-controller-field-props - UIライブラリのため Controller フィールドプロップを正しく配線
• ctrl-single-usecontroller-per-component - コンポーネントあたり単一の useController を使用
• ctrl-local-state-combination - UI のみの状態のため ローカル状態を useController と組み合わせ

4. 検証パターン (高)

• valid-resolver-caching - リゾルバーキャッシングのためコンポーネント外でスキーマを定義
• valid-dynamic-schema-factory - 動的検証のためスキーマファクトリーを使用
• valid-error-message-strategy - オプショナルチェーンまたは lodash get でエラーにアクセス
• valid-inline-vs-resolver - 複雑なルールのためインライン検証よりリゾルバーを優先
• valid-delay-error - 急速なエラー表示をデバウンスするため delayError を使用
• valid-native-validation - シンプルなフォームのためネイティブ検証を検討

5. フィールド配列 (中～高)

• array-use-field-id-as-key - useFieldArray マップのキーとして field.id を使用
• array-complete-default-objects - フィールド配列操作のため完全なデフォルトオブジェクトを提供
• array-separate-crud-operations - 順序的なフィールド配列操作を分離
• array-unique-fieldarray-per-name - フィールド名ごとに単一の useFieldArray インスタンスを使用
• array-virtualization-formprovider - 仮想化されたフィールド配列のため FormProvider を使用

6. 状態管理 (中)

• formstate-destructure-formstate - レンダー前に formState プロパティを分割代入
• formstate-useformstate-isolation - 隔離された状態購読のため useFormState を使用
• formstate-getfieldstate-for-single-field - 単一フィールド状態アクセスのため getFieldState を使用
• formstate-subscribe-to-specific-fields - useFormState で特定のフィールド名に購読
• formstate-avoid-isvalid-with-onsubmit - onSubmit モードでのボタン状態のため isValid を避ける

7. 統合パターン (中)

• integ-shadcn-form-import - shadcn Form コンポーネントのインポート元を確認
• integ-shadcn-select-wiring - スプレッド演算子の代わりに onValueChange で shadcn Select を配線
• integ-mui-controller-pattern - Material-UI コンポーネントのため Controller を使用
• integ-value-transform - 型強制のため Controller レベルで値を変換

8. 高度なパターン (低)

• adv-formprovider-memo - React.memo で FormProvider 子要素をラップ
• adv-devtools-performance - 本番環境とパフォーマンステスト中に DevTools を無効化
• adv-testing-wrapper - QueryClient と AuthProvider を使用してテストラッパーを作成

使用方法

詳細な説明とコード例について、個別のリファレンスファイルを参照してください：

• セクション定義 - カテゴリー構造と影響度レベル
• ルールテンプレート - 新規ルール追加用テンプレート
• リファレンスファイル: references/{prefix}-{slug}.md

関連スキル

• Zod リゾルバーを使用したスキーマ検証については、zod スキルを参照
• React 19 サーバーアクションについては、react-19 スキルを参照
• UI/UX フォーム設計については、frontend-design スキルを参照

フルコンパイル版ドキュメント

すべてのルール展開を含む完全なガイド: AGENTS.md