Wix Data Collection Builder
Creates CMS data collections for Wix CLI apps. The data collections extension allows your app to automatically create CMS collections when it's installed on a site. Collections store structured data that can be accessed from dashboard pages, site pages, backend code, and external applications.
Important:
This extension automatically enables the site's code editor, which is required for the Wix Data APIs to work. Without this extension, apps using Data APIs would need the Wix user to manually enable the code editor on their site, which isn't guaranteed. With the data collections extension, your app can reliably use Data APIs to read and write data in the collections.
App Namespace Handling
App namespace is REQUIRED
for data collections to work. The namespace scopes your collection IDs to prevent conflicts between apps.
Implementation Behavior
If app namespace is provided in the prompt:
Use it in all code examples:
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?" Access Context Who Sees / Uses It Implication Site Widget ( SITE_WIDGET ) Any site visitor (public) Reads must be ANYONE . If the widget accepts input (e.g., reviews, submissions), inserts must also be ANYONE or SITE_MEMBER . Embedded Script Any site visitor (public) Same as site widget — reads must be ANYONE . Writes depend on whether visitors can submit data. Dashboard Page ( DASHBOARD_PAGE ) Site owner / collaborators only Can use CMS_EDITOR or PRIVILEGED for all operations since only authorized users access the dashboard. Backend code (site-side) Runs in visitor context If called from page code or site-side modules, the caller has visitor-level permissions — data must be readable/writable at the appropriate public level. Backend code (elevated) Runs with auth.elevate() from @wix/essentials Can bypass permissions, but the collection still needs correct defaults for any non-elevated callers. How to apply this: Identify every place the collection is read or written — site widgets, dashboard pages, embedded scripts, backend APIs. 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). 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/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: The blueprint ALSO includes a DASHBOARD_PAGE extension that needs to manage data the widget displays OR the widget explicitly needs to display MULTIPLE records of user-generated/business data (not configuration) 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/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/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. Verification After implementation, use wix-cli-app-validation to validate TypeScript compilation, build, preview, and runtime behavior. Reference Documentation extension-template.ts - Template for src/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