commerce-app-init

新しい Commerce アプリを初期化する

基本的な Adobe Commerce アプリをスキャフォールディングします。メタデータを含む app.commerce.config.ts を作成し、 続いて init を実行して依存関係をインストールし、必要なプロジェクトファイルをすべて生成します。 拡張性ドメイン（イベント、webhook、ビジネス設定）は、ドメインスキルを使って個別に追加します。

ステップ 1 — 設定を作成する

プロジェクトのルートに app.commerce.config.ts がすでに存在する場合は、上書きせず、ステップ 2 に進んでください（このスキルは、設定がすでにあるアプリで再度実行しても安全です）。それ以外の場合は、ユーザーの意図に基づいて以下のフィールドの値を導き出し、確認してから、ファイルをプロジェクトのルートに書き込みます。

// app.commerce.config.ts
import { defineConfig } from "@adobe/aio-commerce-lib-app/config";

export default defineConfig({
  metadata: {
    id: "my-commerce-app", // alphanumeric + hyphens only, max 100 chars
    displayName: "My Commerce App", // shown in App Management UI, max 50 chars
    description: "...", // max 255 chars
    upgradeMode: "manual", // optional; currently defaults to "manual" while upgrade execution stabilizes (will default to "auto" once ready); "auto" (experimental) runs upgrades after deploy and waits for completion, "manual" returns plans without executing them
    version: "1.0.0", // Major.Minor.Patch only, no pre-release identifiers
  },
});

注釈付きテンプレートの全体については、assets/app.commerce.config.ts を参照してください。

ステップ 2 — プロジェクトを初期化する

既存の設定を検出して検証し、プロジェクトのセットアップを行うため、必ず init を実行してください。

npx @adobe/aio-commerce-lib-app init

app.commerce.config.ts がすでに存在するため、init は対話形式のプロンプトをスキップします。再実行しても安全です。設定が存在する場合、依存関係をインストールし、プロジェクトファイルを生成（または再生成）します。app-management パッケージは再生成されますが、src/commerce-extensibility-1/actions/ 以下のユーザーパッケージは保持されます（下記の「プロジェクト構成」を参照）。

TypeScript Commerce 設定の場合、init は不足している webpack-config.cjs とルートの tsconfig.json ファイルも作成し、互換性のある typescript、ts-loader、@tsconfig/bases、@types/node の開発依存関係をインストールして、プロジェクトの合成された typecheck スクリプトに typecheck:actions を追加します。生成される Runtime アクションは JavaScript のままです。このスキャフォールディングの準備ができた後、ユーザーが作成するランタイムアクション（下記のドメインスキルで追加）とカスタムインストールスクリプト（commerce-app-storage）は .ts で記述できます。既存の JavaScript プロジェクトを移行する場合の詳しい手順は、aio-commerce-lib-app の使用ガイドを参照してください。

プロジェクト構成

init の実行後、プロジェクトの src/ 以下には 2 種類のディレクトリがあります。

• src/commerce-extensibility-1/actions/ — webhook とイベント用のカスタムランタイムアクションです。src/commerce-extensibility-1/ext.config.yaml で、ユーザー定義のパッケージ名（フレームワークで予約されている app-management 以外の任意の名前）を指定して登録します。これらは aio app build の実行後も保持されます。ジェネレーターが再生成するのは app-management パッケージのみです。
• src/commerce-extensibility-1/.generated/ — aio app build によって自動生成されます。読み取り専用として扱ってください。ここで手動編集した内容は上書きされます。
• src/commerce-configuration-1/ — aio app build によって管理されます。読み取り専用として扱ってください。
• ルートの tsconfig.json — TypeScript Commerce 設定と生成された Runtime アクションをチェックします。独自の TypeScript 設定を持つ Admin UI の web-src は対象外です。

ステップ 3 — 設定を検証する

すべてが有効であることを確認するため、プロジェクトをビルドします。

aio app build

設定が無効な場合、ビルドは、問題のあるフィールドを示す詳細な検証エラーとともに失敗します。

よくある問題

• id の検証エラー：metadata.id には英数字とハイフンのみ使用できます。ドット、アンダースコア、スペースは使用できません。アップグレード時に変更することはできません。別の ID を使用するには、アプリをアンインストールして再インストールしてください。
• version の検証エラー：数値のみの semver（1.0.0）が受け付けられます。プレリリース識別子（1.0.0-beta）はサポートされていません。
• defineConfig が見つからない：@adobe/aio-commerce-lib-app がインストールされ、@adobe/aio-commerce-lib-app/config からインポートされていることを確認してください。

品質基準

• aio app build がエラーなく完了すること

連携

aio app build が成功した後：

1. Developer Console をセットアップする — App Builder のセットアップ（Console プロジェクト／ワークスペース、API サブスクリプション、デプロイ、実行、ワークスペースの接続）に関する後続のトピックでは、スキル appbuilder-project-init（adobe/skills）を呼び出します。次の点を伝えてください：

   • Commerce のスキャフォールドはすでに存在するため、aio app init の手順はスキップします
   • 実行時の IMS 認証情報の同期に必要なため、ワークスペースのセットアップの一環として AdobeIOManagementAPISDK（I/O Management API）をサブスクライブします
   • ワークスペースが作成されたら、Commerce バックエンドが ACCS（Adobe Commerce as Cloud Service）か PaaS かをユーザーに確認します。ACCS の場合は、ACCS-REST-API もサブスクライブする必要があります。aio console open を実行してブラウザーでワークスペースを開き、Developer Console の UI から手動で追加します。ユーザーが追加を確認するまで、先に進まないでください。

   appbuilder-project-init がインストールされていない場合は、まずインストールするようユーザーに依頼します：

   npx skills add adobe/skills --skill appbuilder-project-init -y
   

2. ドメインスキルで拡張する — ワークスペースの接続が完了したら：

   • commerce-app-eventing — Commerce と外部イベントソースを管理します
   • commerce-app-webhooks — Webhook のインターセプトを管理します
   • commerce-app-business-config — カスタムのビジネス設定を管理します
   • commerce-app-admin-ui — カスタム列、一括アクション、注文表示ボタン、メニュー項目で Commerce Admin UI を拡張します
   • commerce-app-storage — 実行時アクションを永続的でクエリ可能な DB ストレージで支えます

参考資料

• assets/app.commerce.config.ts — 最小構成の設定テンプレート