vtex-io-app-contract

アプリの契約とビルダーの境界

このスキルを使用する場面

VTEX IO アプリとは何か、どの機能を宣言するか、また manifest.json を通じてどの統合境界を公開するかが主な判断事項である場合に、このスキルを使用してください。

• 新しい VTEX IO アプリを作成し、初期契約を定義する
• アプリの機能に合わせてビルダーを追加または削除する
• dependencies と peerDependencies のどちらを使用するか選択する
• 機能を現在のアプリに含めるか、別のアプリに移すかを判断する
• マニフェストレベルの契約に関する問題が原因の、link または publish の失敗をトラブルシューティングする

次の用途には、このスキルを使用しないでください。

• service.json、メモリ、ワーカー、ルートの公開など、サービスのランタイム動作
• HTTP ハンドラーの実装、ミドルウェアの構成、イベント処理
• GraphQL スキーマ、リゾルバー、データ取得の実装
• ストアフロント、管理画面、レンダーランタイムのフロントエンド動作
• ポリシーのモデリングとセキュリティ境界の適用

判断ルール

• manifest.json をアプリの契約として扱います。アプリの識別情報、ビルダー、依存関係、ピア依存関係、および他のアプリやプラットフォームが依存する高レベルの機能を宣言します。
• アプリが実際にその機能を所有している場合にのみ、ビルダーを追加します。ビルダーを将来の作業のためのプレースホルダーとして使わないでください。
• 契約の範囲を絞ります。マニフェストに無関係な関心事が含まれるようになった場合は、あらゆる機能を詰め込んだアプリを作るのではなく、それらの関心事を別々のアプリに分けてください。
• 現在のアプリ契約の一部として安全に自動インストールできるアプリにのみ、dependencies を使用します。環境内にすでに存在している必要があるアプリ、外部で管理する必要があるアプリ、または billingOptions を宣言するアプリには、peerDependencies を使用します。
• 公開可能な命名とバージョン管理を維持します。vendor、name、version は、リンク、公開、安全な利用が可能な安定した識別情報を構成する必要があります。
• billingOptions をアプリの商用契約に合わせます。アプリに課金上の影響がある場合は、料金動作を暗黙のままにせず、マニフェストで明示的に宣言してください。
• billingOptions を宣言するアプリは、dependencies を通じて利用できません。現在のアプリが課金対象のアプリを必要とする場合は、その関係を peerDependencies でモデル化し、アカウントまたはエディションの所有者による手動インストールを必須にしてください。
• エディションアプリはアプリ契約の組み合わせであり、例外ではありません。ホスト環境をまたいでも組み合わせが予測可能になるよう、基盤となる各アプリの契約を明示的かつ狭い範囲に保ち、セマンティックバージョニングに安全なものにしてください。
• manifest.json ではアプリレベルの権限や設定項目も宣言できますが、詳細なポリシーモデリングはセキュリティに特化したスキルで扱い、詳細な settingsSchema の設計はアプリ設定のスキルで扱います。

これはビルダーの網羅的な一覧ではありません。すべてのビルダーについては、公式の Builders ドキュメントを参照してください。

ビルダーの所有権に関する参考情報：

ビルダー	アプリ契約に次の機能が含まれる場合、このビルダーを所有します
node	このアプリが所有するバックエンドランタイム機能
graphql	このアプリが所有する GraphQL スキーマの公開
react	このアプリが所有する React バンドル
admin	このアプリが所有する管理画面の UI
store	このアプリが所有する Store Framework ブロックの登録
messages	このアプリが所有するローカライズ済みメッセージバンドル
pixel	このアプリが所有するストアフロントへのピクセルの挿入
masterdata	このアプリが所有する Master Data スキーマアセット

契約境界の判断基準：

1. 機能をこのアプリとともに提供、バージョン管理、保守する場合は、そのビルダーをここで宣言します。
2. 機能を別のアプリから利用するだけの場合は、ビルダーを重複して定義するのではなく、依存関係を宣言します。
3. 機能によって別個のランタイム、セキュリティモデル、またはリリースサイクルが生じる場合は、別のアプリへの分割を検討します。

厳守すべき制約

制約：リリースするすべての機能をマニフェストの契約で宣言する必要があります

アプリに処理可能な VTEX IO 機能が含まれる場合、manifest.json で対応するビルダーを宣言する必要があります。フォルダーが存在するだけで機能すると見なしたり、VTEX IO がリポジトリ構造から機能を推測すると考えたりしないでください。 同様に、実際にはこのアプリでリリースされない機能のビルダーを宣言しないでください。

重要な理由

VTEX IO は意図ではなく、宣言されたビルダーに基づいてアプリをコンパイルし、リンクします。ビルダーがない場合、プラットフォームはその機能を無視し、アプリの契約は実態と一致しなくなります。想定した機能がない状態で、アプリの一部だけがリンクされることがあります。

検出方法

管理対象の /node、/react、/graphql、/admin、/store、/messages、/pixel、または /masterdata ディレクトリがある場合は、作業を中断し、対応するビルダーが manifest.json に存在することを確認してください。ビルダーが存在しても機能がない場合は、作業を中断し、ビルダーを削除するか、その機能を対象範囲に戻してください。

正しい例

{
  "vendor": "acme",
  "name": "reviews-platform",
  "version": "0.4.0",
  "builders": {
    "node": "7.x",
    "graphql": "1.x",
    "messages": "1.x"
  }
}

誤った例

{
  "vendor": "acme",
  "name": "reviews-platform",
  "version": "0.4.0",
  "builders": {
    "messages": "1.x"
  }
}

アプリにはバックエンドと GraphQL の機能が含まれていますが、宣言されているのは messages のみです。そのため、実行時の契約が不完全で、プラットフォームは宣言されていないビルダーを無視します。

制約：アプリの識別情報とバージョンは、公開可能で semver に準拠している必要があります

vendor、name、version フィールドは、有効な VTEX IO アプリの契約を示す必要があります。アプリ名にはケバブケースを使用し、ベンダー名は所有者と一致させ、完全なセマンティックバージョニングを使用してください。

重要な理由

利用者、ワークスペース、リリースフローは、アプリの識別情報が安定していることを前提としています。無効な名前や不完全なバージョンは、リンクや公開を妨げます。また、識別情報の変更によって、安全でないアップグレードやデバッグが困難な依存関係の不一致が発生します。

検出方法

大文字、アンダースコア、semver に準拠しないバージョン、または無関係な作業に混在するベンダー名やアプリ名の変更が見られる場合は、作業を中断し、その変更が意図的でリリース上安全かどうかを確認してください。

正しい例

{
  "vendor": "acme",
  "name": "order-status-dashboard",
  "version": "2.1.0"
}

誤った例

{
  "vendor": "AcmeTeam",
  "name": "Order_Status_Dashboard",
  "version": "2.1"
}

名前がケバブケースではなく、バージョンも有効な semver ではないため、この識別情報では安全に公開できません。

制約：コンテンツを保持するアプリのメジャーバージョンを上げると、保存済みコンテンツが無効になります

アプリに store/blocks.json、store/routes.json、store/templates/、または store/contentSchemas.json のいずれかが含まれる場合（つまり、Store Framework の意味でのコンテンツを保持するアプリの場合）、version フィールドはマーチャント向けの値として扱う必要があります。このアプリで vtex release major を実行すると、vtex.pages-graphql が各 Site Editor の編集内容、各カスタムルート、各テンプレートのレンダーキャッシュを検索する際に使用するキーのプレフィックスが変わります。

重要な理由

vtex.pages-graphql は、マーチャントのコンテンツを [email protected]:template をキーとして管理します。パッチまたはマイナーのバージョンアップではキーは維持されますが、メジャーバージョンアップではキーが変わります。メジャーバージョンアップ後、以前に作成されたコンテンツはすべて、現在のメジャーバージョンのキーではリゾルバーから参照できなくなり、ストアフロントにはデフォルトの vtex.store-theme コンテンツが表示されます。公式の復旧方法は、新しいメジャーバージョンをインストールした後、プロモーションの前に、本番フラグを有効にした開発ワークスペースで [email protected] の updateThemeIds ミューテーションを実行することです。これにより、すべての Site Editor の編集内容、ページ、リダイレクトのキーが旧メジャーバージョンから新メジャーバージョンに変更されます。

検出方法

builders に "store" を宣言しているアプリ、または store/ 以下にファイルがあるアプリで vtex release major を承認する前に、作業を中断し、本番フラグを有効にした開発ワークスペースで updateThemeIds を実行する移行計画を明示するよう求めてください。同じルールは、そのようなアプリの新しいメジャーバージョンを本番アカウントにインストールする前にも適用されます。

正しい例

# patch and minor preserve content keys; safe for content-holding apps
vtex release patch
vtex release minor

誤った例

# major bump on a content-holding app installed straight to master:
# every Site Editor edit becomes invisible to the resolver and the
# storefront falls back to default vtex.store-theme content. The fix
# is to install the new major in a production-flag dev workspace and
# run updateThemeIds in [email protected] before promote.
vtex release major
vtex publish
vtex install [email protected]

コンテンツを保持するアプリの安全なインストール、updateThemeIds による移行、スモークテスト、プロモーション、ロールバックの手順については、vtex-io-storefront-theme-versioning を参照してください。

制約：dependencies と peerDependencies でインストールの意図を正しく表現する

このアプリが契約の一部としてインストールすべきで、安全に自動インストールできるアプリに限り、dependencies を使用してください。環境にすでに存在している必要があるアプリ、外部で管理する必要があるアプリ、または billingOptions を宣言しているアプリには、peerDependencies を使用してください。

重要な理由

これは、アプリと VTEX IO ワークスペースの他の部分との間の、契約における中核的な境界です。依存関係を誤って分類すると、インストールの失敗、見えにくい結合、そして link または publish の後に初めて表面化する環境固有の動作につながります。特に、builder-hub は billingOptions を宣言しているアプリへの依存関係を拒否します。

検出

アプリがすべての環境で機能するために別のアプリを必要とする場合は、作業を止めて、それが dependencies と peerDependencies のどちらに属するかを確認してください。対象のアプリが billingOptions を宣言している場合は、作業を止めて peerDependencies に移してください。アプリがプラットフォーム機能、ホストアプリ、エディション管理のアプリ、またはアカウント側で手動管理することが想定される有料アプリとの連携に限られる場合は、作業を止めて dependencies に含めないでください。

正しい例

{
  "dependencies": {
    "vtex.search-graphql": "0.x"
  },
  "peerDependencies": {
    "vtex.store": "2.x",
    "vtex.paid-app-example": "1.x"
  }
}

誤った例

{
  "dependencies": {
    "vtex.store": "2.x",
    "vtex.paid-app-example": "1.x"
  },
  "peerDependencies": {}
}

この契約では、通常は外部で管理すべきホストアプリを強制的にインストールし、さらに請求対象となるアプリを自動インストールしようとしていますが、これは builder-hub に拒否されます。

推奨パターン

まず、アプリにとって最小限で有用な契約を決め、その契約に必要なアプリの識別情報とビルダーだけを宣言してください。

サービスと GraphQL に特化したアプリに推奨されるマニフェスト：

{
  "vendor": "acme",
  "name": "reviews-platform",
  "version": "0.1.0",
  "title": "Reviews Platform",
  "description": "VTEX IO app that owns review APIs and review GraphQL exposure",
  "builders": {
    "node": "7.x",
    "graphql": "1.x",
    "messages": "1.x"
  },
  "billingOptions": {
    "type": "free"
  },
  "dependencies": {
    "vtex.search-graphql": "0.x"
  },
  "peerDependencies": {
    "vtex.store": "2.x"
  }
}

推奨される契約の分割：

reviews-platform/
├── manifest.json        # identity, builders, dependencies, peerDependencies
├── node/                # backend capability owned by this app
├── graphql/             # GraphQL capability owned by this app
└── messages/            # app-owned translations

reviews-storefront/
├── manifest.json        # separate release surface for storefront concerns
├── react/
└── store/

バックエンド／API 契約とストアフロント契約で、所有者、リリースサイクル、または統合の境界が異なる場合は、この分割を使用してください。

よくある失敗

• アプリがまだ所有していない、将来的な機能のためのビルダーを宣言することで、実際の実装よりも広範な契約にしてしまう。
• バックエンドの実行環境、フロントエンドのレンダリング、設定、ポリシー、統合に関する内容を 1 つの大きなマニフェストで表現する。これらは複数のスキルまたはアプリに分割すべきです。
• ホストレベルのアプリを、peerDependencies にして外部管理すべきにもかかわらず、dependencies に含める。
• 0.x、1.x、3.x などのメジャーバージョン範囲ではなく、依存関係のバージョンを厳密に固定する。
• manifest.json を、より具体的なスキルで扱うべき実行環境やセキュリティの詳細を詰め込む場所として扱う。
• アプリレベルの設定を契約に含めるかどうかの判断にこのスキルだけを使うのではなく、ここで settingsSchema を定義する。

レビューチェックリスト

• マニフェストには、このアプリが実際に所有し、提供する機能だけが記述されていますか？
• 提供する機能それぞれに、対応するビルダー宣言がありますか？
• アプリの識別情報は公開可能ですか？有効な vendor、ケバブケースの name、完全な semver 形式の version がありますか？
• アプリに課金の動作がある場合、billingOptions は明示され、アプリの契約と整合していますか？
• dependencies と peerDependencies は、インストールの意図に応じて分けられていますか？
• 契約を 2 つのアプリに分割することで、無関係な懸念事項やリリースの結合を減らせますか？
• 実行環境、ルート、GraphQL の実装、フロントエンド、セキュリティの詳細は、このスキルから除外されていますか？
• アプリが store/ 内のファイルを提供する場合、予定しているメジャーバージョンの更新がマーチャントに与える影響を確認しましたか？

関連スキル

• vtex-io-storefront-theme-versioning — アプリが store ビルダーを宣言しており、バージョン変更時に Site Editor のコンテンツを保持または移行する必要がある場合に使用します。
• vtex-io-storefront-theme-app — テーマアプリの store/ ファイルが何を担うべきかを判断する場合に使用します。

参考資料

• マニフェスト - manifest.json のフィールドに関する完全なリファレンス
• ビルダー - ビルダーのカタログと機能の対応関係
• 依存関係 - VTEX IO における依存関係とピア依存関係の動作
• 課金オプション - アプリの課金動作をマニフェストで宣言する方法
• 新しいアプリの作成 - アプリの初期化フローとマニフェストの基本