wix-cli-dashboard-plugin

Wix Dashboard Plugin Builder

Wix CLI アプリケーション用のダッシュボードプラグイン拡張機能を作成します。ダッシュボードプラグインは、Wix のファーストパーティビジネスアプリ（Wix Stores、Wix Bookings、Wix Blog、Wix eCommerce など）が管理するダッシュボードページ上の、あらかじめ定義されたスロットに埋め込まれるインタラクティブなウィジェットです。

ダッシュボードプラグインはスロットの全幅を占め、コンテンツに応じて高さが動的に変わります。

---

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

ダッシュボードプラグインを作成するときは、次の手順に沿って進めてください。

1. 対象のスロット ID を特定します — スロットリファレンスを参照してください
2. プラグインフォルダーを作成します：src/extensions/dashboard/plugins/<plugin-name>/
3. extensions.dashboardPlugin() と一意の UUID を含む <plugin-name>.extension.ts を作成します
4. WixDesignSystemProvider でラップした React コンポーネントを含む <plugin-name>.tsx を作成します
5. 新しい拡張機能をインポートして使用するよう、src/extensions.ts を更新します

アーキテクチャ

ダッシュボードプラグインは、次の 2 つの仕組みで動作します。

1. ビジュアル統合 — サポートされているダッシュボードページのスロットにプラグイン UI を埋め込みます
2. ロジカル統合 — observeState() を使ってプラグインとホストページのデータ間の通信を実装します

ファイルとコードの構成

ダッシュボードプラグインは src/extensions/dashboard/plugins/ に配置します。各プラグインには専用のフォルダーがあります。

src/extensions/dashboard/plugins/
└── <plugin-name>/
    ├── <plugin-name>.extension.ts   # Builder configuration
    └── <plugin-name>.tsx            # React component

注： これは CLI で作成されるデフォルトのフォルダー構成です。これらのファイルは src/ フォルダー内の任意の場所に移動し、extension.ts ファイル内の参照を更新できます。

プラグインビルダーの設定

ファイル：<plugin-name>.extension.ts

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

export const dashboardpluginMyPlugin = extensions.dashboardPlugin({
  id: "{{GENERATE_UUID}}",
  title: "My Dashboard Plugin",
  extends: "<SLOT_ID>",
  component: "./extensions/dashboard/plugins/my-plugin/my-plugin.tsx",
});

重要：UUID の生成

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

ビルダーのフィールド

フィールド	型	説明
id	文字列	一意のプラグイン ID（GUID）です。プロジェクト内のすべての拡張機能で一意である必要があります。
title	文字列	プラグインのタイトルです。プロジェクトのダッシュボードでプラグインを参照するために使用されます。
extends	文字列	プラグインをホストするダッシュボードページのスロット ID です。スロットリファレンスを参照してください。
component	文字列	プラグインのコンテンツコンポーネント（.tsx ファイル）への相対パスです。

extends フィールド

extends フィールドでは、プラグインをホストするダッシュボードページのスロットを指定します。Wix の各ビジネスアプリは、ダッシュボードページにスロットを公開しています。正確なスロット ID を指定する必要があります。

重要： 同じ ID のスロットが、ダッシュボード内の異なるページに存在する場合があります。複数のページに存在するスロット用のプラグインを作成すると、そのプラグインは該当するすべてのページに表示されます。

利用可能なスロット ID の一覧については、スロットリファレンスを参照してください。

プラグインコンポーネント

ファイル：<plugin-name>.tsx

プラグインコンポーネントは、ダッシュボードページのスロット内に描画される React コンポーネントです。

import type { FC } from "react";
import { WixDesignSystemProvider, Card, Text } from "@wix/design-system";
import "@wix/design-system/styles.global.css";

const Plugin: FC = () => {
  return (
    <WixDesignSystemProvider features={{ newColorsBranding: true }}>
      <Card>
        <Card.Header title="My Plugin" />
        <Card.Divider />
        <Card.Content size="medium">
          <Text>Plugin content goes here.</Text>
        </Card.Content>
      </Card>
    </WixDesignSystemProvider>
  );
};

export default Plugin;

プラグインコンポーネントで利用可能なリソース

• React — コンポーネントのロジックと状態管理
• Wix SDK — Wix のビジネスソリューションとサイトデータへのアクセス
• Wix Dashboard SDK（@wix/dashboard）— スロットに渡されたダッシュボードページのデータとのやり取り
• Wix Design System（@wix/design-system）— Wix 独自のダッシュボード UI に合った、ネイティブのような React コンポーネント

ダッシュボードデータとのやり取り

Dashboard SDK の observeState() を使用して、ホストのダッシュボードページからデータを受け取ります。

import { dashboard } from "@wix/dashboard";
import { useEffect, useState } from "react";

const Plugin: FC = () => {
  const [params, setParams] = useState<Record<string, unknown>>({});

  useEffect(() => {
    dashboard.observeState((componentParams) => {
      setParams(componentParams);
    });
  }, []);

  return (
    <WixDesignSystemProvider features={{ newColorsBranding: true }}>
      <Card>
        <Card.Content size="medium">
          <Text>Received data: {JSON.stringify(params)}</Text>
        </Card.Content>
      </Card>
    </WixDesignSystemProvider>
  );
};

ホストアプリからの型付き Props

一部の Wix アプリでは、スロットパラメーター用の型付きインターフェイスが公開されています。アプリのダッシュボードパッケージからインポートしてください。

import type { plugins } from "@wix/blog/dashboard";

type Props = plugins.BlogPosts.PostsBannerParams;

const Plugin: FC<Props> = (props) => {
  // props are typed according to the Blog Posts slot contract
};

注： 型付き Props を利用できるかどうかは、Wix アプリによって異なります。各アプリの SDK ドキュメントを確認してください。すべてのスロットで型付きパラメーターインターフェイスが提供されるわけではありません。

拡張機能の登録

拡張機能の登録は必須であり、次の 2 つの手順が必要です。

ステップ 1：プラグイン固有の拡張ファイルを作成する

各ダッシュボードプラグインには、フォルダー内に <plugin-name>.extension.ts ファイルが必要です。上記のプラグインビルダーの設定を参照してください。

ステップ 2：メインの拡張ファイルに登録する

重要： プラグイン固有の拡張ファイルを作成したら、wix-cli-extension-registration を必ず読み、「アプリの登録」セクションに従って src/extensions.ts を更新してください。

ステップ 2 を完了しないと、ダッシュボードプラグインはダッシュボードページに表示されません。

サイズの動作

• ダッシュボードプラグインは、スロットの全幅を使用します
• スロット内のコンテンツに応じて、高さは動的に調整されます
• Dashboard SDK または dashboard-react SDK を使用する場合、コンテンツに応じて寸法が動的に変化します

トラブルシューティング

症状	原因	対処方法
ダッシュボードページにプラグインが表示されない	登録が不足している	src/extensions.ts でインポートし、.use() を呼び出します
ダッシュボードページにプラグインが表示されない	スロット ID が間違っている	extends フィールドがスロットのリファレンスに記載された有効なスロット ID と一致することを確認します

厳守事項

• 新しい型、モジュール、関数、props、イベント、インポートを作り出したり、あると仮定したりしないでください。提供されたリファレンス、またはこのプロジェクトですでに使用されている標準ライブラリに明示的に存在する要素のみを使用してください
• コード内でモック、プレースホルダー、TODO を絶対に使用しないでください。常に、本番環境で使える完全な機能を実装してください
• extends フィールドには、Wix のビジネスアプリの有効なスロット ID を必ず指定してください。スロット ID を作り出してはいけません
• アサーションよりも型の絞り込みと網羅的なロジックを優先してください。非 null アサーション（!）や安全でないキャスト（as any）は避けてください
• // @ts-ignore や // @ts-expect-error は使用しないでください。代わりに型を修正するか、ガードを追加してください

例

ブログ投稿バナープラグイン

リクエスト：「Wix Blog の投稿ページに、プロモーションバナーを表示するプラグインを作成してください」

出力： 投稿データにアクセスするため observeState() を使用し、プロモーションコンテンツを表示する Card コンポーネントを備えた、スロット 46035d51-2ea9-4128-a216-1dba68664ffe（ブログ投稿ページ）を対象とするプラグインです。

Bookings スタッフカレンダーウィジェット

リクエスト：「Wix Bookings のスタッフページに、週ごとの空き状況を表示するプラグインを追加してください」

出力： observeState() を使用してスタッフデータを受け取る、スケジュール表示コンポーネントを備えた、スロット 261e84a2-31d0-4258-a035-10544d251108（Bookings スタッフページ）を対象とするプラグインです。

注文詳細プラグイン

リクエスト：「eCommerce の注文ページに、フルフィルメントのステータスを表示するプラグインを作成してください」

出力： observeState() を使用して注文データにアクセスし、ステータスバッジとフルフィルメントの詳細を表示する、スロット cb16162e-42aa-41bd-a644-dc570328c6cc（eCommerce 注文ページ）を対象とするプラグインです。

出力に関する制約

トークン制限： 出力の上限は約 10,000 トークンです。この制限を超えないように回答を計画してください。

• 大きなファイル（300 行超）を作成する場合は、インポートを使って複数の小さなファイルに分割してください
• タスクに直接必要なファイルのみを出力してください
• 明示的に求められていない限り、README.md やドキュメントファイルを追加しないでください