wix-cli-backend-event

Wix CLI バックエンドイベント拡張機能

Wix CLI アプリケーション向けのイベント拡張機能を作成します。イベントは、アプリプロジェクトの場合は Wix ユーザーのサイトで、ヘッドレスプロジェクトの場合はプロジェクトのサイトで特定の条件が発生するとトリガーされます。プロジェクトは、JavaScript SDK の Webhook を基盤とするイベント拡張機能を使って応答します。CLI は、プロジェクトをこれらの Webhook に登録します。

一般的な用途：連絡先の作成、注文、予約の確定、ブログ投稿の公開時にロジックを実行します。

クイックスタートチェックリスト

イベント拡張機能を作成するときは、次の手順を順番に実行してください。

1. イベントフォルダーを作成します：src/extensions/backend/events/<event-name>/
2. SDK イベントのインポートとハンドラー関数を含む <event-name>.ts を作成します
3. extensions.event() と一意の UUID を含む <event-name>.extension.ts を作成します
4. src/extensions.ts を更新して、新しい拡張機能をインポートして使用します

ユーザー（手動）： 必要に応じて、アプリダッシュボードでイベントのアプリ権限を設定します。バージョンをリリースし、イベントをトリガーしてテストします。

参考資料

トピック	参考資料
一般的なイベント（CRM、eCommerce、Bookings、Blog）	COMMON-EVENTS.md

出力構成

イベントごとに2つのファイルを作成します（ドキュメント）。アプリ内で許可されるハンドラーはイベントごとに1つだけです（ダッシュボードのハンドラーも含みます）。

src/extensions/backend/events/<event-name>/
├── <event-name>.extension.ts   # Builder: extensions.event({ id, source }) – id is unique GUID
└── <event-name>.ts             # Handler: imports SDK event (e.g. onContactCreated), runs on trigger

実装パターン

イベントビルダー（<event-name>.extension.ts）

@wix/astro/builders の extensions.event() を使用します。必須フィールドは id（一意の GUID）と source（ハンドラーファイルへのパス）です。

import { extensions } from "@wix/astro/builders";

export const eventContactCreated = extensions.event({
  id: "{{GENERATE_UUID}}",
  source: "./extensions/backend/events/contact-created/contact-created.ts",
});

重要：UUID の生成

id は一意で静的な UUID v4 文字列である必要があります。拡張機能ごとに新しい UUID を生成してください。randomUUID() を使用したり、例の UUID をコピーしたりしないでください。{{GENERATE_UUID}} を、"a1b2c3d4-e5f6-7890-abcd-ef1234567890" のように新しく生成した UUID に置き換えます。

イベントハンドラー（<event-name>.ts）

正しい SDK モジュールからイベントをインポートし、ハンドラーを渡します。イベントが発生すると、Wix はイベントペイロードとメタデータを使ってハンドラーを呼び出します。ハンドラーのシグネチャについては、JavaScript SDK リファレンスに記載されています。

import { onContactCreated } from "@wix/crm/events";

onContactCreated((event) => {
  console.log("Contact created:", event.entity);
  // Custom logic: sync to CRM, send welcome email, etc.
});

ハンドラーは async にできます。1つのハンドラーの失敗がほかのハンドラーに影響しないよう、エラーを捕捉してログに記録してください。

拡張機能の登録

次の2つの手順が必要です。

手順1：イベントビルダーファイル

上記の実装パターンに従って、イベントフォルダー内に <event-name>.extension.ts（およびハンドラー用の <event-name>.ts）を作成します。

手順2：メインの extensions.ts に登録

重要： wix-cli-extension-registration を読み、イベント拡張機能を src/extensions.ts に追加します（インポートして .use(eventContactCreated) などを呼び出します）。これを行わないと、イベント拡張機能は有効になりません。

命名規則：エクスポート名は event{CamelCaseName} にします（例：eventContactCreated、eventOrderPaid）。

API 呼び出しの権限を昇格する

イベントハンドラー内から Wix API を呼び出す場合は、@wix/essentials の auth.elevate を使用して、適切な権限で呼び出しを実行します。

import { auth } from "@wix/essentials";
import { items } from "@wix/data";

onContactCreated(async (event) => {
  const elevatedQuery = auth.elevate(items.query);
  const result = await elevatedQuery("MyCollection").find();
  // Use result
});

主な制約

• イベントごとにハンドラーは1つ – アプリ内で同じイベントに対するイベント拡張機能を2つ登録することはできません（ローカルとダッシュボードの両方が対象です）。
• 権限 – イベントごとに特定の権限スコープが必要な場合があります。アプリダッシュボードの「Permissions」ページで設定してください。
• テスト – 変更を含むバージョンをリリースしてから、イベントをトリガーする操作を実行します。一部のイベントはローカル開発環境では十分にテストできません。
• バックエンドの制限 – イベントハンドラーにはバックエンド拡張機能の制限が適用されます（例：リクエストあたり CPU 1000 ms、サブリクエスト20件）。バックエンド拡張機能についてを参照してください。

ベストプラクティス

• エラー処理: ハンドラーのロジックを try/catch で囲み、ログを記録して、必要に応じて再スローまたは報告します。
• 冪等性: イベントは複数回配信される可能性があるため、可能な場合はハンドラーを冪等に設計します。
• ログ記録: デバッグには console.log を使用し、本番環境のログは最小限に抑え、機密情報を含めないようにします。
• パフォーマンス: バックエンドの制限時間内に処理を完了します。必要に応じて、負荷の高い処理をキューやバックグラウンドジョブに移します。

イベント拡張機能のテスト

1. 変更を含むバージョンをリリースします。
2. 操作を行ってイベントをトリガーします。