Wix Cli Data Collection

If app namespace is NOT provided:

• Use the placeholder <app-namespace> in all code examples: <app-namespace>/collection-suffix
• Add to Manual Action Items: "Replace <app-namespace> with your actual app namespace from Wix Dev Center"

Collection ID Format

• In extension definition (idSuffix): Use just the suffix, e.g., "products"
• In API calls: Use the full scoped ID: "<app-namespace>/products" — MUST match idSuffix exactly (case-sensitive, no camelCase/PascalCase transformation)
• In referencedCollectionId: Use the idSuffix only (not the full scoped ID) — the system resolves it automatically
• Example: If idSuffix is "product-recommendations", API calls use "<app-namespace>/product-recommendations" NOT "<app-namespace>/productRecommendations"

File Structure

In Wix CLI apps, all CMS collections are defined in a single file:

File: src/extensions/data/extensions.ts

This file uses the extensions.genericExtension() pattern from @wix/astro/builders to register all collections:

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
      ],
    },
  },
});

CRITICAL: The compId must be a unique, static UUID string. Generate a fresh UUID v4 for each app - do NOT use randomUUID() or copy UUIDs from examples. After creating or modifying this file, follow wix-cli-extension-registration for UUID generation and to register the extension in src/extensions.ts (required for collections to work).

Key points:

• Single file contains all collections
• Uses extensions.genericExtension() from @wix/astro/builders
• Each collection includes: idSuffix, displayName, displayField, fields, dataPermissions, and optionally initialData
• displayField specifies which field the CMS displays when referencing items in this collection from other collections
• Collections are generated by merging operations (INSERT, UPDATE, DELETE) with existing collections
• See extension template for complete structure

Field Types

CRITICAL: OBJECT fields require objectOptions. When using type: "OBJECT", you MUST include the objectOptions property — the API will reject OBJECT fields without it. Use an empty object {} if you don't need schema validation:

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

For structured objects, define nested fields inside 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" }
    ]
  }
}

Field Properties

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

Naming Conventions

• Field keys: lowerCamelCase, ASCII only (e.g., productName, isActive, createdAt)
• Collection IDs (idSuffix): lower-kebab-case or lower_underscore (e.g., product-categories, blog_posts)
• Display names: Human-readable, can contain spaces (e.g., "Product Name", "Is Active")

System Fields (Automatic)

Every collection includes: _id, _createdDate, _updatedDate, _owner

Permissions

Access levels control who can read, create, update, and delete items in collections.

Common patterns:

• Public content (default, recommended): read: ANYONE, write: PRIVILEGED
• User-generated content: read: SITE_MEMBER, write: SITE_MEMBER_AUTHOR
• Editorial workflow: read: ANYONE, write: CMS_EDITOR
• Private/admin: read: PRIVILEGED, write: PRIVILEGED

Permission hierarchy (most to least restrictive): PRIVILEGED > CMS_EDITOR > SITE_MEMBER_AUTHOR > SITE_MEMBER > ANYONE > UNDEFINED

Context-Based Permission Rules

CRITICAL: Permissions must match where and how the data is accessed. The consumer of the data determines the minimum permission level — setting permissions more restrictive than the access context will cause runtime failures (empty results or permission-denied errors).

Determine permissions by asking: "Who interacts with this data, and from where?"

How to apply this:

1. Identify every place the collection is read or written — site widgets, dashboard pages, embedded scripts, backend APIs.
2. Use the least restrictive context as the floor. If a site widget reads the data AND a dashboard page also reads it, itemRead must be ANYONE (because the widget is public).
3. Apply per-operation. A collection can have itemRead: ANYONE (widget displays it) but itemInsert: CMS_EDITOR (only dashboard users add items). Each operation is independent.

Examples by blueprint type:

• Dashboard manages data, site widget displays it: itemRead: ANYONE, itemInsert: CMS_EDITOR, itemUpdate: CMS_EDITOR, itemRemove: CMS_EDITOR
• Site widget collects user submissions (e.g., reviews), dashboard moderates: itemRead: ANYONE, itemInsert: ANYONE, itemUpdate: CMS_EDITOR, itemRemove: CMS_EDITOR
• Members-only widget reads data, members can submit: itemRead: SITE_MEMBER, itemInsert: SITE_MEMBER, itemUpdate: SITE_MEMBER_AUTHOR, itemRemove: CMS_EDITOR
• Dashboard-only (no public surface): itemRead: CMS_EDITOR, itemInsert: CMS_EDITOR, itemUpdate: CMS_EDITOR, itemRemove: CMS_EDITOR

Anti-pattern: Setting itemRead: PRIVILEGED on a collection that a site widget queries — the widget will return empty results for all visitors because they lack privileged access.

Relationships

One-to-One / Many-to-One (REFERENCE):

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

Many-to-Many (MULTI_REFERENCE):

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

CRITICAL Constraints:

• REFERENCE/MULTI_REFERENCE fields can ONLY link to other custom CMS collections defined in your app
• The referencedCollectionId MUST be the idSuffix of another collection in the same plan
• NEVER use REFERENCE fields to link to Wix business entities (Products, Orders, Contacts, Members, etc.)
• Use Wix SDK APIs to access Wix business entities instead

Collection Operations

Collections support three operation types for modifying collections:

INSERT

Creates a new collection or replaces an existing one with the same idSuffix.

Use when: Creating a new collection or completely replacing an existing collection.

UPDATE

Modifies an existing collection by merging new data with existing fields.

Use when: Adding fields, updating permissions, or modifying collection properties.

Behavior:

• If collection exists: Merges new data with existing collection
• If collection doesn't exist: Treats update as insert (creates new collection)

DELETE

Removes a collection from the app.

Use when: Removing a collection that is no longer needed.

Behavior:

• Removes the collection from src/extensions/data/extensions.ts
• If all collections are deleted, the entire file is deleted

Merge logic: Operations are applied using a Map keyed by idSuffix. Existing collections are loaded into the Map first, then each operation modifies it: INSERT sets/replaces, UPDATE merges with existing (or creates if missing), DELETE removes. The final Map values become the output collections.

App Version Updates

Changes to your data collections extension require releasing a new major version of your app. When a user updates to the new major version, their collections are updated as follows:

• Adding a new collection: The new collection is created on the site.
• Removing a collection: If the old app version defined a collection and the new version doesn't, the collection is removed from the site.
• Modifying a collection schema: Field additions, removals, and type changes are applied to the collection. Existing data is preserved.

Important notes:

• Collection changes only affect users who update to the new major version. Users who don't update retain their current collections.
• Collection changes take up to 5 minutes to propagate after an update.
• Initial data is only imported when a collection is first created. If a collection already contains data, initialData is ignored during updates.

Wix CLI-Specific Constraints

Embedded Script Parameters vs Collections

CRITICAL: NEVER create CMS collections to store configuration for embedded scripts.

All embedded script configuration must go through embedded script parameters (embeddedScriptParameters), not CMS collections.

DO NOT create collections for:

• Colors, messages, headlines, text content
• Coupon codes, display settings
• UI customization (positions, sizes, styles)
• Timing settings, feature toggles
• Display frequencies, thresholds
• Minimums/maximums
• ANY configuration that controls how an embedded script behaves or appears

Examples of configuration (use parameters, NOT collections):

• Popup headline → embedded script parameter
• Coupon code → embedded script parameter
• Background color → embedded script parameter
• Display position → embedded script parameter
• Show/hide toggles → embedded script parameter

CMS collections should ONLY be created for:

• Business data (products, orders, inventory, etc.)
• User-generated content (reviews, comments, submissions)
• Event logs (if explicitly requested for analytics/tracking)
• Multi-record relational data that is NOT configuration

Decision Rule:

• If it controls HOW the embedded script works or looks → it's configuration → use embedded script parameters
• If it's business data or user-generated content → it's data → use CMS collections

Site Widget Settings vs Collections

CRITICAL: Site widgets have a built-in settings panel (panel.tsx) that handles ALL widget configuration.

For SITE_WIDGET-only blueprints (no DASHBOARD_PAGE or other extensions):

• ALWAYS return collections: [] (empty array)
• The widget panel handles everything
• NEVER create collections to store widget configuration data

Configuration handled by widget panel (NOT collections):

• Target date/time for countdown → widget panel
• Display colors, fonts, sizes → widget panel
• Headlines, labels, messages → widget panel
• Feature toggles, show/hide options → widget panel
• Numeric settings (delays, intervals, thresholds) → widget panel

Only create collections for SITE_WIDGET when ALL of these conditions are met:

1. The blueprint ALSO includes a DASHBOARD_PAGE extension that needs to manage data the widget displays
2. OR the widget explicitly needs to display MULTIPLE records of user-generated/business data (not configuration)
3. AND the data is NOT configuration (dates, colors, settings, display options are ALWAYS configuration)

Anti-Patterns

Don't create aggregated fields. If you have individual rating fields, calculate averages dynamically — don't store computed values like averageRating.

Don't duplicate configuration. If embedded script parameters already hold { headline, color }, don't also create a CMS collection with the same data.

Don't create single-value collections. A collection with one field like { theme: "dark" } should be an embedded script parameter or widget setting instead.

Initial Data Rules

Each item in initialData must match the collection schema exactly:

• Field keys must be lowerCamelCase and match the schema
• TEXT → string, NUMBER → number, BOOLEAN → boolean
• DATE/DATETIME → use { "$date": "2024-01-15T10:30:00.000Z" } format
• REFERENCE → provide the idSuffix of the referenced collection
• Required fields must always have values

Examples

Simple Collection with Initial Data

Request: "Create a collection for handling fees with example data"

Generated file: 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 },
          ],
        },
      ],
    },
  },
});

Collection with Reference Relationship

Request: "Create collections for products and categories with relationships"

Collections:

• categories - Category definitions
• products - Products that reference categories

Both collections are defined in the same src/extensions/data/extensions.ts file, with the products collection using a REFERENCE field to link to categories. See the extension template for a complete multi-collection example.

Common Patterns

Soft Delete: Add isDeleted (BOOLEAN, default: false)

Status/Workflow: Add status (TEXT) with values like draft/pending/published

URL Slug: Add slug (TEXT, unique) for SEO-friendly URLs

Owner Tracking: Add createdBy (REFERENCE → custom collection, not Members)

Note: For owner tracking, create a custom collection for users rather than referencing Wix Members directly.

Reference Documentation

• extension-template.ts - Template for src/extensions/data/extensions.ts

Public Documentation

• About Data Collections Extensions - When to use the extension, implementation options, and app version update behavior
• Add a Data Collections Extension in the App Dashboard - Step-by-step guide to configuring collections via the app dashboard JSON editor, with example configuration
• Data Collections Extension JSON Reference - Complete JSON schema and field definitions for the data collections extension