wix-cli-cms-collection（WIX CLI CMS collection 搜索）

Wix CMS Collection Builder

Creates CMS collections (databases) for Wix CLI apps. Collections store structured data that can be accessed from dashboard pages, site pages, backend code, and external applications.

File Structure

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

File: src/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. See EXTENSIONS.md for UUID generation instructions.

Key points:

• Single file contains all collections
• Uses extensions.genericExtension() from @wix/astro/builders
• Each collection includes: idSuffix, displayName, fields, dataPermissions, and optionally initialData
• Collections are generated by merging operations (INSERT, UPDATE, DELETE) with existing collections
• See extension template for complete structure
• See GENERATION.md for detailed technical information about the generation process

Non-Matching Intents

Do NOT use this skill for:

• Querying/reading data → Use dashboard page or backend code
• Dashboard UI for data → Use wix-cli-dashboard-page
• Backend API endpoints → Use wix-cli-backend-api
• Data migration → Manual process

Field Types

Complete reference: See FIELD_TYPES.md for detailed documentation of all 24+ field types, including examples, constraints, and use cases.

Field Properties

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

System Fields (Automatic)

Every collection includes: _id, _createdDate, _updatedDate, _owner

Permissions

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

Default pattern (recommended):

• read: ANYONE, write: PRIVILEGED - Public read, admin write

Common patterns:

• Public content: 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

Complete reference: See PERMISSIONS.md for detailed documentation of all access levels, security best practices, and permission patterns.

Automatic Permission Forcing:

All permissions are automatically forced to ANYONE for collections with INSERT or UPDATE operations, regardless of what permissions are specified in the plan. This automatic override applies to all four permission fields (itemRead, itemInsert, itemUpdate, itemRemove). See PERMISSIONS.md for more details.

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

Output Structure

All collections are defined in a single file:

src/
└── data/
    └── extensions.ts    # All collections defined here

This file exports a dataExtension using extensions.genericExtension() that contains all collection definitions.

Extension Registration

CRITICAL: After creating or modifying src/data/extensions.ts, you MUST read ../../skills/references/EXTENSIONS.md and follow the "App Registration" section to update src/extensions.ts.

Without this step, the CMS collections will not be available in your app.

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/data/extensions.ts
• If all collections are deleted, the entire file is deleted

Technical details: See GENERATION.md for how operations are merged and applied, including the getDataExtensionAndCollectionsFiles function.

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)

Additional patterns and anti-patterns: See CODEGEN_PATTERNS.md for app namespace scoping, initial data guidelines, field naming conventions, and common anti-patterns.

Examples

Simple Collection with Initial Data

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

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

Note: Replace {{GENERATE_UUID}} with a freshly generated UUID v4 string.

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/data/extensions.ts file, with the products collection using a REFERENCE field to link to categories.

Complete examples: See EXAMPLES.md for more real-world examples including collections with references, multi-references, complex fields, and multiple collections.

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.

Verification

After implementation, use wix-cli-app-validation to validate TypeScript compilation, build, preview, and runtime behavior.

Reference Documentation

• FIELD_TYPES.md - Complete field types reference with examples
• PERMISSIONS.md - Access levels and security best practices
• CODEGEN_PATTERNS.md - Wix CLI-specific constraints and patterns
• GENERATION.md - Technical details about collection generation process (getDataExtensionAndCollectionsFiles)
• EXAMPLES.md - Real-world collection examples
• extension-template.ts - Template for src/data/extensions.ts