Build and review Wix CLI app extensions — dashboard pages, modals, plugins, menu plugins, custom element widgets, Editor React components, site plugins, embedded scripts, backend APIs, backend events, service plugins, data collections, and App Market readiness. Use when building ANY feature or extension for a Wix CLI app or preparing a Wix app for App Market review. Triggers on: add, build, create, implement, help me, dashboard, widget, plugin, backend, API, event, collection, embedded script, service plugin, Editor React component, checkout, shipping, tax, discount, SPI, CMS, schema, tracking, popup, admin panel, menu item, modal, validate, test, verify, register extension, App Market, app review, submission readiness.
Build and review Wix CLI app extensions — dashboard pages, modals, plugins, menu plugins, custom element widgets, Editor React components, site plugins, embedded scripts, backend APIs, backend events, service plugins, data collections, and App Market readiness. Use when building ANY feature or extension for a Wix CLI app or preparing a Wix app for App Market review. Triggers on: add, build, create, implement, help me, dashboard, widget, plugin, backend, API, event, collection, embedded script, service plugin, Editor React component, checkout, shipping, tax, discount, SPI, CMS, schema, tracking, popup, admin panel, menu item, modal, validate, test, verify, register extension, App Market, app review, submission readiness.
compatibility
requires `@wix/cli` >= 1.1.192.
Wix App Builder
Helps build extensions for Wix CLI applications. Covers all extension types: dashboard pages, modals, plugins, menu plugins, custom element widgets, Editor React components, site plugins, embedded scripts, backend APIs, events, service plugins, and data collections.
Scaffolding is owned by the Wix CLI. For every extension type except Backend API, files, folders, builder boilerplate, UUIDs, and src/extensions.ts registration are generated by wix generate --params. This skill provides the decision logic, API guidance, configuration semantics, and business-logic patterns that fill in the generated stubs.
⚠️ MANDATORY WORKFLOW CHECKLIST ⚠️
Before reporting completion to the user, ALL boxes MUST be checked:
Step 1: Determined extension type(s) needed
Asked clarifying questions if requirements were unclear
🛑 Auto-Patterns Gate (MANDATORY): If the use case is a single-collection CRUD admin page (table/grid + entity form), you MUST use AUTO_PATTERNS_DASHBOARD.md. Auto-patterns is the DEFAULT; custom Dashboard Pages are the opt-out. Only fall back to Dashboard Page if a disqualifier applies: multi-collection joins, custom business logic, embedded script configuration, external API integrations, or the user explicitly requested a custom React page.
🛑 Iteration Gate (MANDATORY): Before editing ANY file under src/extensions/dashboard/pages/<page>/, check for a sibling patterns.json. If it exists, this is an auto-patterns page — you MUST follow AUTO_PATTERNS_DASHBOARD.md Part B and use the override topic-index (banners → custom-slots-override.md, header → custom-header-override.md, actions → custom-actions-override.md, columns → custom-columns-override.md, sections → custom-sections-override.md). Do NOT edit the page component (<page-name>.tsx) to add UI elements directly.
Checked for implicit Data Collection need — unless user provided a collection ID directly (see Data Collection Inference)
Obtained app namespace if Data Collection extension is being created
Determined full scoped collection IDs if Data Collection extension is being created (see Collection ID Coordination)
Explained recommendation with reasoning
Step 2: Read extension reference file(s) for the chosen type(s) and the project-wide CODE_QUALITY.md
Step 3: Checked API references; used MCP discovery only for gaps
Step 4a: Scaffolded each CLI-supported extension via wix generate --params
Step 4b: Filled in business logic in the generated files
Invoked wix-design-system skill ONLY before editing the first .tsx/.jsx file that imports @wix/design-system. Skip for backend-only or data-only extensions.
WDS: imported @wix/design-system/styles.global.css in the main component entry file (page.tsx, modal .tsx, etc.) — not child/tab/helper files.
Existing Wix app dashboard (menu item) → Dashboard Menu Plugin
Anywhere on site → custom element widget
Anywhere on site (with editor manifest) → Editor React component
Wix business solution page → Site Plugin
During business flow → Service Plugin
After event occurs → Backend Event Extension
Decision Flow (Not sure?)
Admin: Single-collection CRUD admin page? → Auto Patterns Dashboard (DEFAULT). Custom React page (multi-collection / custom logic / embedded scripts / external APIs / explicit user request)? → Dashboard Page. Need popup/form? → Dashboard Modal. Extending Wix app dashboard with a visual widget? → Dashboard Plugin. Adding a menu item to a Wix app dashboard's more-actions or bulk-actions menu? → Dashboard Menu Plugin. Modal constraint: Dashboard Pages cannot use <Modal />; use a separate Dashboard Modal extension and dashboard.openModal().
Backend: During business flow (checkout/shipping/tax)? → Service Plugin. After event (webhooks/sync)? → Backend Event Extension. Custom HTTP endpoints? → Backend API. Need CMS collections for app data? → Data Collection.
Site: User places anywhere (standalone)? → custom element widget. Editor React component with editor manifest (styling, content, elements)? → Editor React component. Fixed slot on Wix app page? → Site Plugin. Scripts/analytics only? → Embedded Script.
CRITICAL: Data collections are often needed implicitly — don't wait for the user to explicitly say "create a CMS collection." Infer the need automatically.
Skip this section if the user provides a collection ID directly (e.g., an existing site-level collection). In that case, use the provided ID as-is — no Data Collection extension or namespace scoping needed.
Always include a Data Collection extension when ANY of these are true:
Indicator
Example
User mentions saving/storing/persisting app-specific data
"save the fee amount", "store product recommendations"
A dashboard page will manage (CRUD) domain entities
"dashboard to manage fees", "admin page to edit rules"
A service plugin reads app-configured data at runtime
"fetch fee rules at checkout", "look up shipping rates"
User mentions "dedicated database/collection"
"save in a dedicated database collection"
Multiple extensions reference the same custom data
Dashboard manages fees + service plugin reads fees
Why this matters: Without the Data Collection extension, the collection won't be created when the app is installed, the Wix Data APIs may not work (code editor not enabled), and collection IDs won't be properly scoped to the app namespace.
If data collection is inferred, follow the App Namespace Requirement to obtain the namespace before proceeding.
App Namespace Requirement
When creating a Data Collection, you MUST ask the user for their app namespace from Wix Dev Center. This is a required parameter that must be obtained from the user's Dev Center dashboard and cannot be recommended or guessed.
If the user hasn't provided their app namespace, read APP_IDENTIFIERS.md and give the user the instructions to obtain it.
Collection ID Coordination
Applies ONLY when a Data Collection extension is being created. If the user provides a collection ID directly, use it as-is — no namespace scoping, no Data Collection extension needed.
When a Data Collection is created alongside other extensions that reference the same collections:
Get the app namespace (see App Namespace Requirement above)
Determine the idSuffix for each collection (the Data Collection reference documents the full ID format)
Use the full scoped collection ID (<app-namespace>/<idSuffix>) in all extensions that reference the collection via Wix Data API calls
Wix Stores Versioning Requirement
Applies when ANY Wix Stores API is used (products, inventory, orders, etc.):
Read the Stores Versioning reference — see STORES_VERSIONING.md. It contains the module map, permissions cheatsheet, copy-paste dual-catalog recipes (list/get/create/update/delete products, inventory, categories), the V1→V3 field map, webhook mapping, and the major V3 gotchas. Use it before searching SDK docs — it covers the common 80%.
All Stores operations must check catalog version first using getCatalogVersion()
Use the correct module based on version: productsV3 (V3) vs products (V1)
Apps MUST support both V1 and V3 — single-version apps cannot list in the App Market and break on new sites
Request both V1 and V3 permission scopes for every Stores operation
This is non-negotiable — V1 and V3 are NOT backwards compatible.
App Market Review
Applies when a user wants to submit their app to the Wix App Market, list it publicly, prepare for App Market review, audit decline risk, or fix App Market review feedback. Not needed for private apps or routine version releases.
Read APP_MARKET_REVIEW.md — it contains the full technical checklist, implementation notes with Wix doc links, and the review taxonomy IDs for traceability.
Implementation Workflow
Step 1: Ask Clarifying Questions (if needed)
Only ask for configuration values when absolutely necessary for the implementation to proceed. If a value can be configured later or added as a manual step, don't block on it.
If unclear on approach (placement, visibility, configuration, integration), ask clarifying questions. If the answer could change the extension type, wait for the response before proceeding. Otherwise, proceed with the best-fit extension type.
Step 2: Make Your Recommendation
Use the Extension Types Reference Table and decision content above. State extension type and brief reasoning (placement, functionality, integration).
Step 3: Read Extension Reference, Check API References, Then Discover (if needed)
Workflow: Read extension reference → Check API references → Use MCP only for gaps.
Read the extension reference file for the chosen extension type from the table above
Wix Stores API — include Stores Versioning reference
"Show booking calendar"
✅ YES (MCP discovery)
Wix Bookings API not in reference files
"Send emails to users"
✅ YES (MCP discovery)
Wix Triggered Emails not in reference files
"Get member info"
✅ YES (MCP discovery)
Wix Members API not in reference files
"Listen for cart events"
Check COMMON-EVENTS.md
MCP discovery only if event missing in reference
"Store data in collection"
WIX_DATA.md ✅ Found
❌ Skip discovery (covered by reference)
"Create CMS collections for my app"
Data Collection reference
❌ Skip discovery (covered by dedicated reference)
"Show dashboard toast"
DASHBOARD_API.md ✅ Found
❌ Skip discovery
"Show toast / navigate"
DASHBOARD_API.md ✅ Found
❌ Skip discovery
"UI only (forms, inputs)"
N/A (no external API)
❌ Skip discovery
"Settings page with form inputs"
N/A (UI only, no external API)
❌ Skip discovery
"Dashboard page with local state"
N/A (no external API)
❌ Skip discovery
MCP Tools for discovery (when needed):
SearchWixSDKDocumentation - SDK methods and APIs (Always use maxResults: 5)
ReadFullDocsMethodSchema - Full type schema for a specific SDK method (parameters, return type, permissions)
ReadFullDocsArticle - Prose guides and conceptual articles only (not for SDK method signatures)
Step 4a: Scaffold via the CLI
For each extension except Backend API, run npx wix generate --params '<json>'. The command returns {"success":true,"extensionType":"...","newFiles":[...]} on success.
If the command fails because of unknown or invalid params, run npx wix schema generate --type <extensionType> to print the JSON Schema for that extension type, fix the --params payload, and retry. Do not fall back to manual scaffolding.
What the CLI does automatically:
Creates folders and stub files
Generates a fresh UUID for the extension id
Updates src/extensions.ts with the import and .use() call
Backend API exception: Create src/pages/api/*.ts files manually per BACKEND_API.md.
Step 4b: Fill in business logic
Open every path returned in newFiles and replace stubbed handler bodies / UI / queries with the user's actual logic, guided by the extension reference file's API and configuration sections.
⚠️ MANDATORY when using WDS: Invoke the wix-design-system skill before editing your first .tsx/.jsx file that imports @wix/design-system. Do NOT invoke it preemptively for backend-only or data-only jobs — it adds large content to context that you won't use.
⚠️ MANDATORY when using WDS: Add import "@wix/design-system/styles.global.css"; in the main component entry file (page.tsx, modal .tsx, etc.) — not in child/tab/helper files.
⚠️ MANDATORY when using Data Collections: Use the EXACT collection ID from idSuffix (case-sensitive). If idSuffix is "product-recommendations", use <app-namespace>/product-recommendations NOT productRecommendations.
Step 5: Run Validation
After all implementation is complete, you MUST run validation. See APP_VALIDATION.md for the complete validation workflow:
Package installation (detect package manager, run install)
TypeScript compilation check (npx tsc --noEmit)
Build validation (npx wix build)
Preview deployment (npx wix preview)
Do NOT report completion to the user until validation passes.
If validation fails, fix the errors and re-validate until it passes.
Step 6: Report Completion
Only after validation passes, provide a concise summary section at the top of your response:
If there are NO manual steps, state: "✅ No manual steps required — you're ready to go!"
Step 7: Surface Manual Action Items
Present any manual steps the user must perform (e.g., configuring settings in the Wix dashboard, enabling permissions, setting up external services).
Format:
## 🔧 Manual Steps Required
The following actions need to be done manually by you:
### 1. [Action Category/Title]
[Detailed description with specific instructions]
### 2. [Action Category/Title]
[Detailed description]
Extension Registration
wix generate --params updates src/extensions.ts automatically for every CLI-supported extension type. The only case that still requires manual editing is Backend API. For background, troubleshooting, and the manual recovery pattern when src/extensions.ts drifts, see EXTENSION_REGISTRATION.md.
Validation
Execute these steps sequentially after all implementation is complete. See APP_VALIDATION.md for the complete guide.
Package Installation — Detect package manager, run install
TypeScript Compilation — npx tsc --noEmit
Build — npx wix build
Preview — npx wix preview
Stop and report errors if any step fails. Check .wix/debug.log on failures.
Cost Optimization
Let the CLI scaffold — don't burn tokens describing folder layouts or builder boilerplate
Only run wix schema generate --type <extensionType> when wix generate --params fails — don't pre-fetch it
Read extension reference first — always read the relevant extension reference file before implementing
Check API references first — read relevant API reference files before using MCP discovery
Skip discovery when all required APIs are in reference files
maxResults: 5 for all MCP SDK searches
ReadFullDocsMethodSchema for SDK method schemas; ReadFullDocsArticle for prose guides only
Invoke wix-design-system first when using WDS (prevents import errors)
Documentation
For links to official Wix CLI documentation for all extension types, see DOCUMENTATION.md.
