大規模コンポーネントライブラリにおける Vue 3 Composition API と Options API の比較

大規模な管理コンポーネントライブラリでこの選択が重要な理由

管理アプリの大規模なコンポーネントライブラリは、数個のボタンしかないマーケティングサイトとは違います。画面全体で繰り返し使われるビルディングブロックが何十、何百とあります。ソートやバルクアクションを備えたデータテーブル、フィルタパネル、検証ルールのあるフォーム、ドロワーとモーダル、確認フロー、日付ピッカーや権限ガードのような小さなユーティリティ――これらがあちこちに現れます。

こうしたパターンが至る所にあると、チームは締め切りを守るためにコードをコピーして調整しがちです。あるテーブルにはカスタムのフィルタバー、別のテーブルには少し違うバーが入り、やがて「ほとんど同じ」実装が五つできあがります。そこでは Composition API と Options API の選択が個人の好みを超え、ライブラリ全体の健全性に影響を与え始めます。

最初に壊れるのは一貫性であることが多いです。UI は動くけれど挙動がずれていきます：ある場所では Escape でモーダルが閉じるが別の場所では閉じない、同じフォームフィールドがあるページでは blur で検証され、別のページでは submit でしか検証されない。次に速度が落ちます。変更のたびにほぼ同じ実装を探し回る必要が出てきます。最後に自信が失われ、誰もリファクタをしたがらなくなります。

共有ライブラリで特に重要な実務的決定は三つです。

• コード再利用: 共有ロジックを絡まり合う依存なしにどうパッケージするか。
• テスト: UI に依存しない挙動の検証をどれだけ容易にするか。
• オンボーディング: 新しいコントリビュータがコンポーネントを読んで安全に変更できるまでの速さ。

単純な例を考えてください：管理画面に 20 のリストページがあり、プロダクトが「保存されたフィルタ」機能を要求したとします。テーブルやフィルタ、URL 同期ロジックが散らばっていて一貫性がなければ、その機能は遅れて出るか、不具合付きで出るかのどちらかです。どの API スタイルを選ぶかが、そのロジックを再利用可能な一箇所に置けるか、各画面にどれだけ明確に結びつけられるか、新しい人がどれだけ簡単に拡張できるかを決めます。

Vue 3 の管理画面（AppMaster のようなプラットフォーム内で Vue 3 を使うチームも含む）を作るなら、早めにこの選択をすることで後々の保守に何ヶ月も節約できます。

Options と Composition が日常のコードでどう違うか

違いを実感する最速の方法は、大きな管理コンポーネントを開いて「この機能の挙動をどこで変えればいい？」と自問することです。コンポーネントライブラリではこの質問が日常的に出てきます。

Options API では、コードが種類別にまとまります：状態は data、アクションは methods、派生値は computed、副作用は watch に。コンポーネントが小さいうちはこの構造は読みやすいです。しかし大きなテーブルやフォームでは、ひとつの機能（バルクアクションやフィールド検証など）のロジックが複数のブロックに分散することがよくあります。整然と保つことは可能ですが、ファイル内を行ったり来たりするワークフローを避けるには規律と一貫した命名が必要です。

Composition API では、コードは機能ごとにまとめられることが多いです。関連する状態、派生値、副作用、ヘルパーを近くに定義し、繰り返しのロジックを composable に切り出せます。管理系ライブラリでは人の思考と合いやすく、例えば「フィルタに関することはここにある」「行選択に関することはここにある」のようにまとまります。usePagination のような composable を複数のテーブルで再利用できることも多いです。

日々の大きな差は依存関係の見え方です。

• Options API は暗黙的に感じられることがあります：あるメソッドが this.user、this.filters、this.loading に依存していて、それを知るにはメソッド内部を読む必要があります。
• Composition API はより明示的になりがちです：関数が filters や loading をクロージャーで捕まえている場合、それらの変数が近くに定義されているのが見え、ヘルパー関数に渡すこともできます。

トレードオフとして、Composition API は何でも setup() に詰め込むと騒々しくなります。

実用的な指針：

• コンポーネントが主に表示用でロジックが軽ければ Options API を選ぶ。
• ライブラリ全体で共有される複数の機能があるなら Composition API を選ぶ。
• Composition API を選んだら、コードを機能別にグループするシンプルなレイアウトに合意する（「refs を先に全部並べる」ではなく）。
• Options API を選んだら、命名規約を強制し、短いコメントと一貫したメソッド名で関連ロジックをまとめる。

どちらでもうまくいきます。重要なのは、次の変更が「賢く見える」より「明白に感じられる」ように組織化することです。

コード再利用：何がきれいにスケールして何が汚くなるか

管理系アプリでは再利用は贅沢ではありません。何十もの画面で同じ振る舞いを繰り返すため、小さな不一致がバグやサポートチケットになります。

再利用の大半は次のような反復的な領域に落ち着きます：バックエンドに合わせたソート/フィルタ/ページネーション、フォーム検証とエラーマッピング、権限チェックや UI のゲーティング、クエリ同期（URL パラメータ、保存ビュー、デフォルトフィルタ）、テーブル選択ルールを伴うバルクアクション。

Options API の再利用：強力だが複雑化しやすい

Options API では、再利用は mixin、extends、プラグインから始まることが多いです。

Mixins は手早いですが、どこからメソッドや算出値が来たのかが隠れてしまいスケールしにくいです。二つの mixin が同じメソッド名でぶつかると、コンポーネントファイルだけでは挙動が分からなくなります。

extends は mixin よりクリーンに感じられるかもしれませんが、複数ファイルを読む必要があり継承のパズルが生じます。プラグインはグローバルなディレクティブや共有サービスのようなアプリレベルの懸念には合いますが、画面ごとに変わるビジネスルールの置き場所としては最適ではありません。

再利用が暗黙的になると、新しいコントリビュータは「このデータはどこから来ている？」に答えられなくなり、コードベース全体を検索しなければならなくなります。

Composition API の再利用：composable は明示的に保たれる

Composition API の再利用は通常 composable を中心に構築されます：refs、computed、ハンドラを返す小さな関数です。大きな利点は、再利用がコンポーネントの上部近くで見えるようになり、隠れたコンポーネントコンテキストに依存する代わりにパラメータを渡せる点です。

例えば usePagination はデフォルトを受け取り一貫した形で変更を通知できますし、usePermissions は現在のロールと機能名を受け取ることができます。ここで問題になるのは構文ではなく、ライブラリが「明示的な配線」を重視するか「暗黙の継承」を許すかです。

再利用を予測可能に保つには、各再利用単位を小さな API のように扱ってください：明確な名前、入力と出力を定義し、単一責務にする。ある composable がページネーション、キャッシュ、権限、通知を全部扱い始めたら分割しましょう。後で一部を差し替える際に他を壊さずに済みます。

フォームやテーブルを苦労せずに再利用可能に作る

管理系アプリではフォームとテーブルが、コンポーネントライブラリの良し悪しを決めます。どちらの API でも可能ですが、共有ロジック（dirty state、エラーマッピング、submit フロー）のパッケージの仕方に差があります。

共有フォームロジックでは、Options API は mixin や共有ヘルパーに寄りがちです。Mixins は最初は便利に感じますが、「このフィールドエラーはどこから来ているのか」「なぜ submit が無効になるのか」といった基本的な疑問に答えにくくなります。

Composition API はこの種の再利用をより見えやすくします。useDirtyState、useFormErrors、useSubmitFlow のような composable にロジックを移せば、フォームコンポーネントが何を取り込んでいるかがはっきり見えます。大規模ライブラリではこの明快さが、数行節約すること以上に価値を持ちます。

コンポーネント API を安定させる実践法は、公開面を契約と見なすことです：props、emits、slots は滅多に変えない。これは両スタイルで同じですが、Composition API は内部を一つの composable ごとに置き換えやすく、テンプレート API に触らずに済むことが多いです。

ライブラリが成長しても健全に保てるパターン：

• 1 つの仕事をよく行うベースコンポーネント（BaseInput、BaseSelect、BaseTable）を作り、それらを機能コンポーネントに合成する。
• レイアウトの柔軟性には slots を優先し、すべてのエッジケースに prop を追加するのは避ける（アクション領域、空状態、セルレンダリングなど）。
• イベントは早めに正規化する（例：update:modelValue、submit、rowClick）とアプリが内部細部に依存しなくなる。
• 検証やフォーマットは入力に近く置き、ビジネスルールは外に出す（composable や親コンテナで）。

過度の抽象化はよくある罠です。あらゆるフィールドタイプや検証ルール、レイアウトオプションを扱う「スーパー・フォーム」は、使いにくくなることが多いです。ベースコンポーネントが全チームの要件をカバーするのにプロップが多すぎるなら、それは二つのコンポーネントに分けるサインかもしれません。

時には複製が正解です。ある画面だけが複雑なマルチ行グルーピングを必要とするなら、小さな断片をコピーしてローカルに保つ方が賢明です。賢い抽象化は保守の摩擦を長く残すことがあるため、新しいコントリビュータが「普通の」コンポーネントとフレームワーク内フレームワークの違いを理解するまで混乱を招きます。

Composition と Options のどちらを選ぶにしても、データフローの可読性を第一に最適化してください。再利用は素晴らしいですが、ユーザーの操作から emit されるイベントへの道筋を隠すようでは意味がありません。

テストへの影響：何が検証しやすくなるか

コンポーネントライブラリのテストは大きく三つの塊に分かれます：純粋なロジック（フォーマット、検証、フィルタリング）、レンダリング（ある状態で何が表示されるか）、インタラクション（クリック、入力、キーボード、emit）。選ぶ API スタイルによって、最初の塊を DOM マウントなしでどれだけテストできるかが変わります。

Options API のテストは「コンポーネントをマウントしてインスタンスの状態を操作し、DOM をアサートする」ような形になりがちです。それは機能しますが、ロジックが methods、computed、watch、ライフサイクルフックに混ざるため大きなテストになりがちです。失敗したときは watcher のタイミングかライフサイクルの副作用かロジック自体かを切り分ける時間が増えます。

Options API は次のようなケースで扱いやすく感じられます：

• ライフサイクル順序に依存するユーザーフロー（mount 時のフェッチ、ルート変更時のリセット）
• watcher 駆動の振る舞い（自動保存、クエリ同期）
• コンポーネントメソッドからのイベント送出（save()、reset()、applyFilter()）

Composition API はバランスを変えます。ロジックを composable に移せば、純粋関数のように小さな入力と明確な出力でユニットテストできます。必要な「マウントしてクリックする」テストの数が減り、失敗箇所が局所化されます。依存関係の扱いも簡単になります：グローバルをモックする代わりに fetch 関数や日付フォーマッタ、権限チェッカーを composable に渡せます。

具体例：ソート、ページネーション、選択行を持つ再利用可能な AdminTable。Composition API なら選択ロジックを useRowSelection() に置き、テーブルをレンダリングせずにトグル、クリア、全選択、ページ跨ぎの保持などをテストできます。コンポーネントテストはテンプレートがボタンやチェックボックス、emit を正しく結びつけていることを確認する小さなテストに留めます。

テストを小さく読みやすく保つための原則（どちらのスタイルでも）：

• ビジネスルールは純関数か composable に入れる。watcher に押し込まない。
• 副作用（fetch、ストレージ、タイマー）は注入可能な依存の背後に隠す。
• コンポーネントごとに集中した統合テストをいくつか用意し、巨大な「全部入り」テストを避ける。
• ライブラリ全体で状態名やイベント名を一貫させる（テスト準備が楽になります）。
• メソッド A が watcher B の実行に依存するような隠れた結合を避ける。

テストの安定性を高めたいなら、ライフサイクル駆動の振る舞いを減らし、DOM なしで検証できる孤立したロジック単位を増やす方向に傾けてください。

新しいコントリビュータのオンボーディング：どれだけ速く戦力になるか

大規模な管理系コンポーネントライブラリでは、オンボーディングは Vue の教えではなく「どこを見ればいいか」「どの規約に従うか」「安全に変更できる自信をどう与えるか」が中心です。遅くなる要因は主に三つ：ナビゲーション（ロジックはどこにあるか）、規約（ここではどうやるか）、自信（変更で五つの画面が壊れないかどうか）。

Options API では新人は初日は比較的早く動けます：props、data、computed、methods、watch の構造が馴染みやすいからです。代償は実際の挙動が散らばるため、サーバー側フィルタリングのような一つの機能が watcher、computed、二つのメソッド、さらに mixin に分かれていることがあります。各ブロックは読めますが、それらをつなげてストーリーにする時間がかかります。

Composition API では、関連ロジックがまとまっているためオンボーディングは速くなり得ますが、composable の読み方に慣れる必要があります。useTableState() のようなパターンや複数の composable を通るリアクティブ値の流れを理解しなければなりません。境界が明確でないと、ファイル間を地図なしに飛び回っているように感じることがあります。

どちらのスタイルでもほとんどの疑問を解消する規約：

• 予測可能な構造を使う：components/、composables/、types/、tests/。
• 命名パターンを決めて守る（例：useX、XTable、XForm）。
• 短いドックブロックを追加する：コンポーネントの目的、主要な props、主要なイベント。
• 新しい composable やヘルパーを追加してよい条件を一つ定義する（エスケープハッチルール）。
• 推奨パターンを示す小さな“ゴールデン”コンポーネントを維持する。

例：チームが Vue 3 の管理パネルを生成してカスタマイズする場合（例えば AppMaster で生成して開発者が拡張するケース）、テーブル挙動（ソート、フィルタ、ページネーション）を調整する明確な場所と UI 配線を調整する明確な場所があるとオンボーディングが大幅に改善します。これはどの API を選ぶかよりも重要です。

ステップバイステップ：スタイルを選んで安全に導入する方法

大規模な管理 UI ライブラリでは、この問題を解決する最も安全な方法は、全体の書き換えではなく、境界がはっきりした機能でパイロットを始めることです。

再利用頻度が高く振る舞いが明確なモジュール（テーブルフィルタやフォーム検証など）を一つ選びます。コードに触る前に現状の動作を書き出してください：入力（props、クエリパラメータ、ユーザー操作）、出力（イベント、emit、URL の変更）、エッジケース（空状態、リセット、サーバーエラー）。

次に境界を決めます。コンポーネント内に留めるべきもの（レンダリング、DOM イベント、アクセシビリティ）と共有コードに移せるもの（フィルタの解析、デバウンス、API パラメータの構築、デフォルト状態）を明確にします。UI の意思決定を共有コードに移すと再利用が難しくなる落とし穴があるので注意してください。

実用的な導入計画：

• パターンを明確に示す、複数の画面で使われているコンポーネントを一つ選ぶ。
• 小さく明示的な API を持つ共有ユニット（composable またはプレーンなヘルパー）を抽出する。
• そのユニットに対する焦点を絞ったテストをまず書く（実際の管理シナリオに基づく）。
• 新しいユニットを使って選んだコンポーネントをエンドツーエンドでリファクタする。
• 同じパターンを別のコンポーネントに適用してスケールするか確認する。

共有 API は地味で明白にしてください。例えば useTableFilters() は初期フィルタを受け取り filters、apply()、reset()、toRequestParams() を公開するだけにするとよいです。グローバル状態から魔法のように読み取る設計は避けましょう。

パイロット後に短い内部ガイドラインを公開し、コントリビュータがコピーできる実例を一つ示してください。「テーブルのフィルタロジックはすべて composable にあり、コンポーネントは UI コントロールをバインドして apply() を呼ぶだけ」という具体的な一行ルールは長いドキュメントより効果があります。

展開前の完了定義の例：

• 新しいコードが二つの異なるコンポーネントで同じように読めること。
• 共有ロジックがフル UI をマウントせずにテストでカバーされていること。
• 新しいコントリビュータがフィルタルールを変更するのに無関係なファイルに触る必要がないこと。

AppMaster のようなノーコードツールで管理ポータルも作っているチームは、同じパイロットの考え方を適用できます：承認のようなワークフローを一つ選び、振る舞いを定義してからパターンを標準化してから横展開します。

大規模ライブラリでよくある間違いと罠

大規模ライブラリの問題は文法の違いではなく、小さな局所決定が積み重なって再利用やテスト、保守を難しくすることにあります。

よくある罠の一つはパターンをランダムに混ぜることです。ライブラリの半分が Options API、残りが Composition API でポリシーがないと、新しいコンポーネントごとにスタイル議論が起きます。同じ問題に対して異なる解決が重複しがちです。両方を許すなら明確な方針を作りましょう：新しいコンポーネントは一つのスタイルを使い、レガシーは必要なときだけ触り、共有ロジックは合意した一箇所に置く、など。

もう一つの罠は「ゴッド composable」です。useAdminPage() や useTable() といった便利な始まりが、ルーティング、フェッチ、キャッシュ、選択、ダイアログ、トースト、権限を次々に吸い込み、テストしにくく再利用しにくくなります。各画面がその 30% しか使わなくても複雑さのコストを全て負うことになります。

Watchers も痛めつける要因です。非同期データやデバウンスされた入力と組み合わせるとタイミングのバグが出やすく、「時々選択がクリアされる」といった再現の難しい不具合に発展します。

ライブラリが危険な方向に向かっている赤信号の例：

• あるコンポーネントが特定の props とイベントの順序でしか動かない。
• composable がグローバル状態を読み書きしていてそれが明示されていない。
• 複数の watcher が同じ状態を更新している。
• リファクタが消費者の画面を小さく壊し続ける。
• 「あのファイル」に誰も触りたがらない。

最後の罠はリファクタ中に公開 API を壊すことです。管理アプリではテーブル、フィルタ、フォームフィールドが素早く広がるため、prop 名の変更、emit の変更、slot 振る舞いの調整が多数の画面を黙って壊します。

安全なアプローチはコンポーネント API を契約として扱うことです：削除するのではなく非推奨にし、互換性のための shim をしばらく残し、消費者の使い方に合わせた簡単な利用テストを追加します。AppMaster のようなツールで生成する Vue 3 管理画面があるチームでは、コンポーネント契約の一貫性が画面の再利用と変更の予測可能性を高めます。

パターンを選ぶ前の簡単チェック

Composition、Options、あるいはその混在を選ぶ前に、ライブラリの実際のコンポーネントでいくつかのチェックを行ってください。目的はシンプル：ロジックを素早く見つけられ、安心して再利用でき、管理者が頼る振る舞いをテストしやすいこと。

1) ロジックは素早く見つかるか？

フィルタ + テーブル + 権限 + バルクアクションがある典型的なコンポーネントを開いて、新しい人になったつもりで考えてください。

良い兆候は「フィルタロジックはどこか」「なにがボタンを無効にしているのか」を 2 分以内に答えられることです。Options API では computed、methods、watch にロジックが明確に分かれていることが求められます。Composition API では setup() が小さな名前付きブロック（または composable）に整理され、巨大な関数を避けていることが求められます。

2) 共有ユーティリティは関数のように振る舞っているか？

どのパターンでも共有コードは明確な入力と出力を持ち、副作用を最小限にすべきです。ヘルパーがグローバル状態に手を伸ばす、渡されたオブジェクトを変更する、ネットワーク呼び出しを何の前触れもなく行うなら再利用は危険になります。

簡単なチェック：

• composable やヘルパーのシグネチャを見て何が返るか想像できるか？
• 隠れたセットアップなしに二つのコンポーネントで使えるか？
• テストでその状態をハックなしにリセットできるか？

3) テストは管理者向けの振る舞いに焦点を当てているか？

管理系アプリは予想される失敗パターンがあります：フィルタが間違って適用される、権限でアクションが漏れる、フォーム検証がばらつく、編集後にテーブル状態が壊れる。

内部実装（watcher と ref の違い）をテストするのではなく、次のような振る舞いでテストを書いてください：「ロール X のときアクション Y は隠れる」「保存でエラーが出ると入力が保持される」「フィルタ変更でクエリと空状態メッセージが更新される」。こうすれば後でスタイルを変えてもテストは安定します。

4) 非同期状態の標準はあるか？

多数の小さな非同期フロー（オプションの読み込み、フィールド検証、テーブル行の取得、失敗時のリトライ）が増えると、各コンポーネントが独自の loading/error を作り始めます。そうなるとオンボーディングとデバッグが遅くなります。

非同期状態の形（loading、error、retries、cancellation）を一つに決めてください。Composition API は useAsyncX() のような再利用可能な composable を作りやすく、Options API は data() と共有メソッドで標準化しやすいです。どちらでも一貫していれば問題ありません。

5) コンポーネント公開 API は安定で自己説明的か？

コンポーネントを製品のように扱ってください。props、emit、slots は契約です。契約が頻繁に変わるとどの管理画面も壊れやすくなります。

意図を説明するコメント（メカニクスではなく何を保証するか）を探してください：どの props が何を意味するか、どのイベントが保証されるか、何が内部扱いか。AppMaster のようなプラットフォームで内部ツールを作るなら、この考え方は特に重要です：安定したビルディングブロックが将来の画面を速く作れるようにします。

例シナリオとあなたのチームの次のステップ

再構築中の管理「Users」ページを想像してください：フィルタバー（ステータス、ロール、作成日）、選択可能な行を持つテーブル、バルクアクション（無効化、削除、エクスポート）、ロールベースのアクセス（管理者だけがバルク削除、マネージャはロール編集可）です。

Composition API と Options API では UI は同じに見えますが、コードの組織は異なりがちです。

Options API では大きなコンポーネントに data（フィルタと選択）、computed（派生状態）、methods（フェッチ、バルクアクション、権限チェック）が詰め込まれることが多く、再利用は mixin や共有ヘルパーとして現れます。フェッチは methods、クエリ同期は watcher、権限は computed にあるような散逸が起きやすいです。

Composition API ではクエリとフィルタ、テーブル選択とバルクアクション、権限のように焦点を絞った composable に分ける傾向があり、ページコンポーネントはこれらを組み立てる役割になります。各関心事のロジックがまとまる一方で、contributor が「setup の中の魔法」を感じないように命名とフォルダ規約が必要です。

再利用はフィルタの URL 同期、サーバーサイドのテーブルパターン（ページネーション、ソート、全選択、バルクアクションのガード）、権限チェックと UI ゲーティング（ボタン、列、行アクション）、一貫した空/ローディング状態の周りに自然に現れます。

一般的な次のステッププラン：

1. 新しいコードのデフォルトスタイルを決め、例外は書面で理由を示すことを要求する。
2. 規約を定義する：composable の置き場所、命名、インポート可能なもの、返すべきもの。
3. この Users ページのような小さなリファレンスページをゴールドスタンダードとして作る。
4. 再利用部（フィルタ、権限、バルクアクション）を先にテストする。
5. 一部の管理画面はスピード優先でノーコード生成（AppMaster 等）にし、手書きライブラリは本当にユニークな部分に集中する。

AppMaster で既に構築しているなら、生成された部分と手書き部分で同じメンタルモデルを保つと便利です：安定したコンポーネント契約と、小さく明示的な単位としての共有ロジック。ノーコードで内部ツールを検討しているチーム向けに、AppMaster (appmaster.io) はバックエンド、Web、モバイルを生成しつつ、カスタマイズ可能な Vue 3 Web UI を標準化する助けになります。

今週あなたが一つだけやるなら、Users ページをテンプレートにしてコードレビューで強制してください。一つの明確な例が長いスタイルガイドよりも一貫性に効きます。