wix-cli-data-collection

Name: wix-cli-data-collection
Author: wix

github.com/wixデータ・データベース36286 回インストール今日更新

リポジトリ

wix-cli-data-collection について

Wix CLI アプリで CMS データコレクションを定義するスキルです。フィールド、権限、関連付け、更新を扱い、アプリ名前空間でスコープされたコレクションを構成します。

主な機能

01共通の拡張ファイルでコレクションを定義
02フィールド型と属性を設定
03操作ごとのアクセス権限を設定
04カスタムコレクション間の参照を定義
05挿入、更新、削除の操作を適用
06アプリ名前空間でコレクション ID を限定

活用シーン

01アプリ固有データの CMS ストレージを作成
02サイト訪問者やダッシュボードの権限を設定
03関連するカスタムコレクションを接続
04アプリのリリース時にコレクション構造を更新

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/wix/skills --skill wix-cli-data-collection

インストール後、Claude Code で/wix-cli-data-collectionを入力して読み込まれたか確認します。

同梱ファイルassets/extension-template.ts

詳細

Wix Data コレクションビルダー

Wix CLI アプリ用の CMS データコレクションを作成します。データコレクション拡張機能を使用すると、サイトへのインストール時にアプリが CMS コレクションを自動的に作成できます。コレクションには構造化データが保存され、ダッシュボードページ、サイトページ、バックエンドコード、外部アプリケーションからアクセスできます。

重要： この拡張機能は、Wix Data API の動作に必要なサイトのコードエディターを自動的に有効にします。この拡張機能がない場合、Data API を使用するアプリでは、Wix ユーザーがサイトのコードエディターを手動で有効にする必要がありますが、必ず有効にされるとは限りません。データコレクション拡張機能を使用すると、アプリは Data API を使ってコレクション内のデータを確実に読み書きできます。

アプリの名前空間の処理

データコレクションを機能させるには、アプリの名前空間が必須です。名前空間によってコレクション ID の範囲を限定し、アプリ間の競合を防ぎます。

実装時の動作

プロンプトでアプリの名前空間が指定されている場合：

すべてのコード例で使用します：<actual-namespace>/collection-suffix

アプリの名前空間が指定されていない場合：

すべてのコード例でプレースホルダー <app-namespace> を使用します：<app-namespace>/collection-suffix
手動アクション項目に次の内容を追加します：「<app-namespace> を Wix Dev Center にある実際のアプリの名前空間に置き換えてください」

コレクション ID の形式

拡張機能の定義（idSuffix）： サフィックスのみを使用します。例："products"
API 呼び出し： スコープ付きの完全な ID を使用します："<app-namespace>/products" — idSuffix と完全に一致する必要があります（大文字と小文字を区別し、camelCase／PascalCase への変換は行いません）
referencedCollectionId： idSuffix のみを使用します（スコープ付きの完全な ID ではありません）。システムが自動的に解決します
例：idSuffix が "product-recommendations" の場合、API 呼び出しでは "<app-namespace>/productRecommendations" ではなく "<app-namespace>/product-recommendations" を使用します

ファイル構成

Wix CLI アプリでは、すべての CMS コレクションを単一のファイルで定義します。

ファイル： src/extensions/data/extensions.ts

このファイルでは、@wix/astro/builders の extensions.genericExtension() パターンを使用してすべてのコレクションを登録します。

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

export const dataExtension = extensions.genericExtension({
  compId: "{{GENERATE_UUID}}",
  compName: "data-extension",
  compType: "DATA_COMPONENT",
  compData: {
    dataComponent: {
      collections: [
        // All collections defined here
      ],
    },
  },
});

重要： compId は一意で静的な UUID 文字列である必要があります。アプリごとに新しい UUID v4 を生成してください。randomUUID() を使用したり、例の UUID をコピーしたりしないでください。このファイルを作成または変更した後、UUID の生成と src/extensions.ts への拡張機能の登録について、wix-cli-extension-registration に従ってください（コレクションを機能させるために必要です）。

要点：

すべてのコレクションを単一のファイルに記述します
@wix/astro/builders の extensions.genericExtension() を使用します
各コレクションには idSuffix、displayName、displayField、fields、dataPermissions が含まれ、必要に応じて initialData も含まれます
displayField は、他のコレクションからこのコレクションの項目を参照する際に、CMS でどのフィールドを表示するかを指定します
コレクションは、既存のコレクションに操作（INSERT、UPDATE、DELETE）をマージして生成されます
完全な構成については、拡張機能のテンプレートを参照してください

フィールドの種類

種類	説明	用途
`TEXT`	1 行のテキスト	名前、タイトル
`RICH_TEXT`	書式設定された HTML テキスト	ブログコンテンツ
`RICH_CONTENT`	メディアを埋め込めるリッチコンテンツ	複雑なブログ記事
`NUMBER`	小数	価格、数量
`BOOLEAN`	真偽値	切り替え、フラグ
`DATE`	日付のみ	誕生日
`DATETIME`	日付と時刻	タイムスタンプ
`TIME`	時刻のみ	スケジュール
`IMAGE`	単一の画像	サムネイル
`DOCUMENT`	ファイル添付	PDF
`VIDEO`	動画ファイル	メディア
`AUDIO`	音声ファイル	ポッドキャスト
`MEDIA_GALLERY`	複数のメディア	ギャラリー
`REFERENCE`	1 つの項目へのリンク	著者 → ユーザー
`MULTI_REFERENCE`	複数の項目へのリンク	投稿 → タグ
`ADDRESS`	構造化された住所	場所
`URL`	URL の検証	リンク
`PAGE_LINK`	Wix ページへのリンク	内部ナビゲーション
`LANGUAGE`	言語コード	多言語コンテンツ
`OBJECT`	JSON オブジェクト	柔軟なデータ
`ARRAY`	値の配列	汎用配列
`ARRAY_STRING`	文字列の配列	タグリスト
`ARRAY_DOCUMENT`	ドキュメントの配列	ファイルコレクション
`ANY`	任意の種類	最も柔軟

重要：OBJECT フィールドには objectOptions が必要です。 type: "OBJECT" を使用する場合は、objectOptions プロパティを必ず含めてください。これがない OBJECT フィールドは API に拒否されます。スキーマ検証が不要な場合は、空のオブジェクト {} を使用してください。

{
  "key": "settings",
  "displayName": "Settings",
  "type": "OBJECT",
  "objectOptions": {}
}

構造化オブジェクトの場合は、objectOptions.fields 内にネストされたフィールドを定義します。

{
  "key": "triggerRules",
  "displayName": "Trigger Rules",
  "type": "OBJECT",
  "objectOptions": {
    "fields": [
      { "key": "url", "displayName": "URL Condition", "type": "TEXT" },
      {
        "key": "scrollDepth",
        "displayName": "Scroll Depth %",
        "type": "NUMBER"
      },
      { "key": "dateStart", "displayName": "Start Date", "type": "DATE" }
    ]
  }
}

フィールドのプロパティ

{
  "key": "email",
  "displayName": "Email Address",
  "type": "TEXT",
  "required": true,
  "unique": true,
  "defaultValue": null,
  "description": "User's primary email"
}

プロパティ	説明
`key`	フィールド識別子（キャメルケース）
`displayName`	CMS に表示されるラベル
`type`	フィールドのデータ型
`required`	値が必須かどうか
`unique`	重複が許可されないかどうか
`defaultValue`	初期値
`description`	ヘルプテキスト

命名規則

フィールドキー： lowerCamelCase。ASCII 文字のみ使用します（例：productName、isActive、createdAt）
コレクション ID（idSuffix）： lower-kebab-case または lower_underscore を使用します（例：product-categories、blog_posts）
表示名： 人が読みやすい名前を使用し、スペースを含めることができます（例："Product Name"、"Is Active"）

システムフィールド（自動）

すべてのコレクションには、_id、_createdDate、_updatedDate、_owner が含まれます。

権限

アクセスレベルは、コレクション内のアイテムを誰が読み取り、作成、更新、削除できるかを制御します。

レベル	説明
`UNDEFINED`	未設定（デフォルトを継承）
`ANYONE`	公開アクセス（訪問者を含む）
`SITE_MEMBER`	サインイン済みのすべてのユーザー（メンバーとコラボレーター）
`SITE_MEMBER_AUTHOR`	サインイン済みのユーザー。ただし、メンバーがアクセスできるのは自身のアイテムのみ
`CMS_EDITOR`	CMS アクセス権限を持つサイトコラボレーター
`PRIVILEGED`	CMS 管理者と特権ユーザー

一般的なパターン：

公開コンテンツ（デフォルト、推奨）：read: ANYONE, write: PRIVILEGED
ユーザー生成コンテンツ：read: SITE_MEMBER, write: SITE_MEMBER_AUTHOR
編集ワークフロー：read: ANYONE, write: CMS_EDITOR
非公開／管理者向け：read: PRIVILEGED, write: PRIVILEGED

権限の階層（制限が強い順）：PRIVILEGED > CMS_EDITOR > SITE_MEMBER_AUTHOR > SITE_MEMBER > ANYONE > UNDEFINED

コンテキストに基づく権限ルール

重要：権限は、データへのアクセス場所と方法に合わせる必要があります。 データを利用する側によって最低限必要な権限レベルが決まります。アクセスコンテキストより制限の強い権限を設定すると、実行時エラー（結果が空になる、または権限拒否エラー）が発生します。

「誰が、どこからこのデータを操作するのか？」と問いかけて権限を決めてください。

アクセスコンテキスト	誰が閲覧／利用するか	影響
サイトウィジェット（`SITE_WIDGET`）	すべてのサイト訪問者（公開）	読み取りには `ANYONE` が必要です。ウィジェットが入力を受け付ける場合（レビューや投稿など）、挿入にも `ANYONE` または `SITE_MEMBER` が必要です。
埋め込みスクリプト	すべてのサイト訪問者（公開）	サイトウィジェットと同様に、読み取りには `ANYONE` が必要です。書き込みの権限は、訪問者がデータを送信できるかどうかによって決まります。
ダッシュボードページ（`DASHBOARD_PAGE`）	サイト所有者／コラボレーターのみ	ダッシュボードにアクセスできるのは認可されたユーザーのみなので、すべての操作に `CMS_EDITOR` または `PRIVILEGED` を使用できます。
バックエンドコード（サイト側）	訪問者のコンテキストで実行	ページコードまたはサイト側モジュールから呼び出された場合、呼び出し元には訪問者レベルの権限が適用されます。データは適切な公開レベルで読み書きできる必要があります。
バックエンドコード（権限昇格）	`@wix/essentials` の `auth.elevate()` を使って実行	権限を迂回できますが、権限昇格を使わない呼び出し元に備えて、コレクションには適切なデフォルト権限が必要です。

適用方法：

コレクションの読み取りまたは書き込みが行われる場所をすべて特定します — サイトウィジェット、ダッシュボードページ、埋め込みスクリプト、バックエンド API。
最も制限の弱いコンテキストを基準にします。 サイトウィジェットとダッシュボードページの両方がデータを読み取る場合、ウィジェットは公開されているため、itemRead は ANYONE にする必要があります。
操作ごとに適用します。 コレクションの itemRead: ANYONE（ウィジェットで表示）と itemInsert: CMS_EDITOR（ダッシュボードユーザーのみアイテムを追加）は併用できます。各操作の権限は独立しています。

ブループリントの種類別の例：

ダッシュボードでデータを管理し、サイトウィジェットで表示： itemRead: ANYONE, itemInsert: CMS_EDITOR, itemUpdate: CMS_EDITOR, itemRemove: CMS_EDITOR
サイトウィジェットでユーザーからの投稿（レビューなど）を受け付け、ダッシュボードでモデレーション： itemRead: ANYONE, itemInsert: ANYONE, itemUpdate: CMS_EDITOR, itemRemove: CMS_EDITOR
メンバー限定ウィジェットでデータを読み取り、メンバーが投稿可能： itemRead: SITE_MEMBER, itemInsert: SITE_MEMBER, itemUpdate: SITE_MEMBER_AUTHOR, itemRemove: CMS_EDITOR
ダッシュボード限定（公開ページなし）： itemRead: CMS_EDITOR, itemInsert: CMS_EDITOR, itemUpdate: CMS_EDITOR, itemRemove: CMS_EDITOR

アンチパターン： サイトウィジェットがクエリするコレクションに itemRead: PRIVILEGED を設定すると、訪問者には特権アクセスがないため、ウィジェットの結果がすべての訪問者に対して空になります。

リレーションシップ

1 対 1／多対 1（REFERENCE）：

{
  "key": "category",
  "displayName": "Category",
  "type": "REFERENCE",
  "referenceOptions": {
    "referencedCollectionId": "categories"
  }
}

多対多（MULTI_REFERENCE）：

{
  "key": "tags",
  "displayName": "Tags",
  "type": "MULTI_REFERENCE",
  "multiReferenceOptions": {
    "referencedCollectionId": "tags"
  }
}

重要な制約：

REFERENCE／MULTI_REFERENCE フィールドでリンクできるのは、アプリで定義された他のカスタム CMS コレクションのみです
referencedCollectionId は、同じプラン内にある別のコレクションの idSuffix である必要があります
Wix のビジネスエンティティ（Products、Orders、Contacts、Members など）へのリンクに REFERENCE フィールドを使用しないでください
Wix ビジネスエンティティへのアクセスには、代わりに Wix SDK API を使用してください

コレクションの操作

コレクションを変更する操作には、次の 3 種類があります。

INSERT

新しいコレクションを作成するか、同じ idSuffix を持つ既存のコレクションを置き換えます。

使用する場面： 新しいコレクションを作成する場合、または既存のコレクションを完全に置き換える場合。

UPDATE

新しいデータを既存のフィールドとマージして、既存のコレクションを変更します。

使用する場面： フィールドの追加、権限の更新、コレクションのプロパティの変更を行う場合。

動作：

コレクションが存在する場合：新しいデータを既存のコレクションとマージします
コレクションが存在しない場合：INSERT として扱い、新しいコレクションを作成します

DELETE

アプリからコレクションを削除します。

使用する場面： 不要になったコレクションを削除する場合。

動作：

src/extensions/data/extensions.ts からコレクションを削除します
すべてのコレクションが削除されると、ファイル全体が削除されます

マージロジック： 操作は、idSuffix をキーとする Map を使用して適用されます。まず既存のコレクションを Map に読み込み、次に各操作で Map を変更します。INSERT は設定または置き換え、UPDATE は既存のコレクションとマージ（存在しない場合は作成）、DELETE は削除を行います。最終的な Map の値が、出力されるコレクションになります。

アプリのバージョン更新

データコレクション拡張機能の変更を反映するには、アプリの新しいメジャーバージョンをリリースする必要があります。ユーザーが新しいメジャーバージョンに更新すると、そのコレクションは次のように更新されます。

新しいコレクションの追加： 新しいコレクションがサイトに作成されます。
コレクションの削除： 古いアプリバージョンで定義されていたコレクションが新しいバージョンにない場合、そのコレクションはサイトから削除されます。
コレクションスキーマの変更： フィールドの追加、削除、型の変更がコレクションに適用されます。既存のデータは保持されます。

重要な注意事項：

コレクションの変更が反映されるのは、新しいメジャーバージョンに更新したユーザーのみです。更新しないユーザーのコレクションは現在の状態のままです。
コレクションの変更が反映されるまで、更新後最大 5 分かかります。
初期データがインポートされるのは、コレクションが初めて作成されるときのみです。 コレクションにすでにデータがある場合、更新時に initialData は無視されます。

Wix CLI 固有の制約

埋め込みスクリプトのパラメーターとコレクション

重要：埋め込みスクリプトの設定を保存するために、CMS コレクションを作成してはいけません。

埋め込みスクリプトの設定はすべて、CMS コレクションではなく、埋め込みスクリプトのパラメーター（embeddedScriptParameters）を使用してください。

次の用途でコレクションを作成しないでください：

色、メッセージ、見出し、テキストコンテンツ
クーポンコード、表示設定
UI のカスタマイズ（位置、サイズ、スタイル）
タイミング設定、機能の有効／無効の切り替え
表示頻度、しきい値
最小値／最大値
埋め込みスクリプトの動作や表示を制御する設定すべて

設定の例（コレクションではなく、パラメーターを使用）：

ポップアップの見出し → 埋め込みスクリプトのパラメーター
クーポンコード → 埋め込みスクリプトのパラメーター
背景色 → 埋め込みスクリプトのパラメーター
表示位置 → 埋め込みスクリプトのパラメーター
表示／非表示の切り替え → 埋め込みスクリプトのパラメーター

CMS コレクションは、次の用途にのみ作成してください：

ビジネスデータ（商品、注文、在庫など）
ユーザー生成コンテンツ（レビュー、コメント、投稿）
イベントログ（分析／トラッキング用に明示的に要求された場合）
設定ではない、複数レコードのリレーショナルデータ

判断基準：

埋め込みスクリプトの動作や外観を制御するもの → 設定 → 埋め込みスクリプトのパラメーターを使用
ビジネスデータまたはユーザー生成コンテンツ → データ → CMS コレクションを使用

サイトウィジェットの設定とコレクション

重要：サイトウィジェットには、すべてのウィジェット設定を処理する組み込みの設定パネル（panel.tsx）があります。

SITE_WIDGET のみのブループリント（DASHBOARD_PAGE やその他の拡張機能を含まない）の場合：

必ず collections: []（空の配列）を返してください
ウィジェットのパネルですべてを処理します
ウィジェットの設定データを保存するために、コレクションを作成してはいけません

ウィジェットのパネルで処理する設定（コレクションではありません）：

カウントダウンの目標日時 → ウィジェットのパネル
表示色、フォント、サイズ → ウィジェットのパネル
見出し、ラベル、メッセージ → ウィジェットのパネル
機能の有効／無効の切り替え、表示／非表示のオプション → ウィジェットのパネル
数値設定（遅延、間隔、しきい値）→ ウィジェットのパネル

次の条件をすべて満たす場合にのみ、SITE_WIDGET 用のコレクションを作成してください：

ブループリントに、ウィジェットが表示するデータの管理に必要な DASHBOARD_PAGE 拡張機能も含まれている
または、ウィジェットがユーザー生成データ／ビジネスデータの複数レコード（設定ではないもの）を明示的に表示する必要がある
さらに、そのデータが設定ではない（日付、色、設定、表示オプションは常に設定です）

アンチパターン

集計フィールドを作成しないでください。 個別の rating フィールドがある場合は、平均値を動的に計算してください。averageRating のような計算済みの値を保存してはいけません。

設定を重複させないでください。 埋め込みスクリプトのパラメーターに { headline, color } がすでにある場合、同じデータを含む CMS コレクションも作成してはいけません。

単一値のコレクションを作成しないでください。 { theme: "dark" } のような単一フィールドだけを持つコレクションは、代わりに埋め込みスクリプトのパラメーターまたはウィジェット設定にしてください。

初期データのルール

initialData の各項目は、コレクションのスキーマと正確に一致させてください：

フィールドキーは lowerCamelCase とし、スキーマと一致させてください
TEXT → 文字列、NUMBER → 数値、BOOLEAN → 真偽値
DATE／DATETIME → { "$date": "2024-01-15T10:30:00.000Z" } 形式を使用してください
REFERENCE → 参照先コレクションの idSuffix を指定してください
必須フィールドには常に値を設定してください

例

初期データを含むシンプルなコレクション

リクエスト：「手数料を処理するためのコレクションを、サンプルデータ付きで作成してください」

生成されるファイル： src/extensions/data/extensions.ts

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

export const dataExtension = extensions.genericExtension({
  compId: "{{GENERATE_UUID}}",
  compName: "data-extension",
  compType: "DATA_COMPONENT",
  compData: {
    dataComponent: {
      collections: [
        {
          schemaUrl: "https://www.wix.com/",
          idSuffix: "additional-fees",
          displayName: "Additional Fees",
          displayField: "title",
          fields: [
            { key: "title", displayName: "Fee Title", type: "TEXT" },
            { key: "amount", displayName: "Fee Amount", type: "NUMBER" },
          ],
          dataPermissions: {
            itemRead: "ANYONE",
            itemInsert: "PRIVILEGED",
            itemUpdate: "PRIVILEGED",
            itemRemove: "PRIVILEGED",
          },
          initialData: [
            { title: "Handling Fee", amount: 5 },
            { title: "Gift Wrapping", amount: 3.5 },
          ],
        },
      ],
    },
  },
});

参照関係を持つコレクション

リクエスト：「商品とカテゴリーのコレクションを、関連付けを含めて作成する」

コレクション：

categories - カテゴリーの定義
products - カテゴリーを参照する商品

両方のコレクションは同じ src/extensions/data/extensions.ts ファイルで定義されており、products コレクションでは、categories との関連付けに REFERENCE フィールドを使用しています。複数のコレクションを含む完全な例については、拡張機能テンプレートを参照してください。

よく使われるパターン

論理削除： isDeleted を追加します（BOOLEAN、デフォルト：false）

ステータス／ワークフロー： status を追加します（TEXT）。値には draft／pending／published などを指定します

URL スラッグ： SEO に適した URL 用に slug を追加します（TEXT、一意）

所有者の追跡： createdBy を追加します（REFERENCE → Members ではなく、カスタムコレクション）

注意： 所有者を追跡するには、Wix Members を直接参照するのではなく、ユーザー用のカスタムコレクションを作成してください。

参考ドキュメント

extension-template.ts - src/extensions/data/extensions.ts のテンプレート

公開ドキュメント

データコレクション拡張機能について - 拡張機能を使用するタイミング、実装方法、アプリのバージョン更新時の動作
アプリダッシュボードでデータコレクション拡張機能を追加する - アプリダッシュボードの JSON エディターでコレクションを設定する手順を、設定例とともに解説します
データコレクション拡張機能の JSON リファレンス - データコレクション拡張機能の完全な JSON スキーマとフィールド定義

Markdown 対応

ログインしてコメント

基本情報

作者: wix
リポジトリ: wix/skills
カテゴリ: データ・データベース
インストール数: 286
GitHub スター: 36

問題を報告