wix-app — Claude Code skill: what it does, how to install
Assists in building Wix CLI app extensions, dashboard pages, widgets, and backend APIs. Prepares applications for Wix App Market review.
MIT 261 installs ★ 40 updated 2026-11-04
npx skills add wix/skills --skill wix-app -a claude-codeWhat wix-app does
File scaffolding stays with the Wix CLI via wix generate --params. The skill supplies the architecture decisions, API guidance, configuration semantics, and business logic patterns. You need @wix/cli version 1.1.192 or higher; running on an older CLI version breaks extension generation.
It enforces strict development gates. If existing Wix app data covers the entity, the skill mandates using the vertical SDK instead of CMS collections. For dashboard UIs, it resolves symbols via patterns-lookup.cjs from published @wix/patterns docs and builds drill-in pages without unrequested SummaryBar widgets.
What it helps with
- scaffold and wire Wix CLI extensions like dashboard pages or modals
- implement backend APIs, custom events, and service plugins
- create custom element widgets and Editor React components
- audit the codebase before submitting to the Wix App Market
Example prompts for the agent
- Create a dashboard page extension to track inventory with Wix CLI
- Implement a custom shipping service plugin and register its backend events
- Review my Wix app extensions for App Market readiness
How to install wix-app
1Skills CLI (Vercel)
npx skills add wix/skills --skill wix-app -a claude-code2Manually: put the files in place
~/.claude/skills/wix-app/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/wix-app/
1Skills CLI (Vercel)
npx skills add wix/skills --skill wix-app -a codex2Manually: put the files in place
.agents/skills/wix-app/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add wix/skills --skill wix-app -a cursor2Manually: put the files in place
.cursor/skills/wix-app/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install wix/skills skills/wix-app2Manually: put the files in place
.github/skills/wix-app/SKILL.md1Skills CLI (Vercel)
npx skills add wix/skills --skill wix-app -a gemini-cli2Platform CLI
gemini skills install https://github.com/wix/skills --path skills/wix-appManually: put the files in place
.devin/skills/wix-app/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add wix/skills --skill wix-app -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about wix-app
How to install wix-app in Claude Code?
Run npx skills add wix/skills --skill wix-app -a claude-code. The skill writes to ~/.claude/skills/wix-app/SKILL.md.
What does wix-app do?
It guides extension architecture across frontend and backend parts of Wix CLI projects. It enforces SDK-first data choices and proper @wix/patterns usage.
What are the prerequisites for wix-app?
The project requires @wix/cli at version 1.1.192 or newer. Extension scaffolding relies directly on the CLI command wix generate --params.
Source text
SKILL.md · MIT
---
name: wix-app
description: "Build and review Wix CLI app extensions — dashboard pages, modals, plugins, menu plugins, custom element widgets, Editor React components, site plugins, embedded scripts, context providers, function libraries, lightbox (popup) behavior, page onLoad contexts, 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, context provider, function library, onLoad, on page load, checkout, shipping, tax, discount, SPI, CMS, schema, tracking, popup, lightbox, 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, context providers, function libraries, backend APIs, events, service plugins, and data collections.
**Scaffolding is owned by the Wix CLI.** Use `wix generate --params` for every supported type. It generates files and, where applicable, builder boilerplate, UUIDs, and `src/extensions.ts` registration. HTTP endpoints are discovered from files and need no registration. 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
- [ ] **🛑 SDK-First Gate (MANDATORY before any Data Collection):** Confirmed the data is NOT owned by an existing Wix app — if it is, use its SDK module, never CMS (see [SDK-First Rule](#sdk-first-rule-existing-wix-app-data-is-never-cms))
- [ ] Checked for implicit Data Collection need — unless user provided a collection ID directly (see [Data Collection Inference](#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](#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](references/CODE_QUALITY.md)
- [ ] **Dashboard page UI:** Translated the prompt into a workflow before choosing components — what the user must understand, focus on, investigate, act on, and see confirmed. See [UX Success Model](references/dashboard-page/UX_SUCCESS_MODEL.md), and the installed package's own `Collection Toolkit.md` guide for which component serves each need ([The Discovery Chain](references/WIX_PATTERNS_DOCS.md#the-discovery-chain)).
- [ ] **No `SummaryBar` unless the request asked for one** — a named total, count, or "how many / how much" figure in the prompt. Not "the page seems like it wants one": an uninvited bar pushes the rows down and puts a number on screen nobody asked to be right about. When the request did ask, the number has to come from something that counts ([QUERY_AND_PAGING.md](references/dashboard-page/QUERY_AND_PAGING.md#what-fetchtotal-is-allowed-to-call)) and be read through `useSelector`, because the state is MobX ([TABLE_STATE.md](references/dashboard-page/TABLE_STATE.md#reading-state-outside-the-table-it-is-mobx)).
- [ ] **A row the user can open, as a page — editable by default** — `navigateToEntityPage` to an `EntityPage` with a working form and save, for CMS and vertical SDK data alike; the three read-only cases are in [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md#2-choose-then-read-the-chosen-templates-page). Unless the prompt is explicitly a report or an export. **Never a `SidePanel`**: in Cairo that hosts a page's own panels.
- [ ] **Every filter reaches the query**: declared in the collection hook's `filters` and read inside `fetchData`. Filter UI that never narrows the rows is a defect that looks like a feature.
A filtered table with no drill-in and no working filters is what gets built when nobody states the requirement — the most common way a generated dashboard disappoints. The aggregate is the judgment call; the drill-in and the filters are not.
- [ ] **🛑 Template-First Gate (MANDATORY, dashboard UI only, comes before writing any shell/provider/router):** Followed [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md): found the page templates the installed `@wix/patterns` ships, chose one with its `Page Templates.md` guide — which pages the workflow above needs, **and where the rows come from** (your own fetch, or a CMS collection) — read that template's page, and copied every file `--templates` lists for it. Composing the page shell, provider nesting, or router wiring from scratch when a template already shows it is the failure mode this gate exists to prevent — the Patterns/Component Docs gates below are for what the template doesn't cover, not a replacement for starting there. The reverse holds too: a template replaces composing the shell, never the discovery chain, so every symbol it doesn't show still goes through the next gate.
- [ ] **🛑 Patterns Docs Gate (MANDATORY for any dashboard page UI):** Read [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md) **before the first command that touches `node_modules/@wix/patterns`** — its discovery chain (`pkg-root.cjs`, the index, `Composition and Providers.md` once, `Collection Toolkit.md` for which component serves a need) lives only in that file, and this line is a summary of its step 1, not a substitute for opening it. Then resolve every patterns name you plan to write in **one** `node <pkgRoot>/bin/patterns-lookup.cjs <name…>` call: per name, it prints the import, the examples and the one props file. Upgrade `@wix/patterns` if `dist/docs/index.json` is missing. Patterns API facts come only from the published `dist/docs/` (pages), `dist/examples/` (worked calls), `dist/dts-bundle/` (types) and `dist/templates/` (whole pages) trees — never from `src/`, `dist/esm/`, `dist/types/`, or any other path inside the package. A prop a bundle has stubbed is in the file its stub names (`Reading the Doc Indices.md`).
- [ ] **🛑 Component Docs Gate (MANDATORY, dashboard UI only):** For each patterns symbol you are about to write, decided **from the lookup output** which single artifact answers the question you actually have — the import line, an example, or the props file — and read only that one. Procedure: [COMPONENT_SELECTION.md](references/dashboard-page/COMPONENT_SELECTION.md). Resolve every patterns name in one `node <pkgRoot>/bin/patterns-lookup.cjs <name…>` call, not one probe per name. State which artifact you read per symbol, and why, before the first line of JSX. Reading a doc *and* its bundle for the same symbol, or opening a page for an import line the lookup already gave you, is the failure this gate exists to prevent.
For the object `useTableCollection()` returns, read [TABLE_STATE.md](references/dashboard-page/TABLE_STATE.md) — a state object you receive rather than construct, whose members are unobvious and several plausible ones absent.
- [ ] **Step 3:** Checked API references; resolved every vertical entity in **one** `sdk-lookup.cjs` call ([SDK lookup](#sdk-lookup-one-call-for-every-vertical-entity)); used the docs only for what it does not print
- [ ] **Dashboard page over Wix data:** took the method from the lookup and verified every mapped field against the declaration it points to (`type … file:line`) — see [DATA_SOURCES.md](references/dashboard-page/DATA_SOURCES.md), and [QUERY_AND_PAGING.md](references/dashboard-page/QUERY_AND_PAGING.md) before writing `fetchData`. A field marked `@deprecated` still compiles and renders something plausible and wrong.
- [ ] **Vertical SDK prerequisites — for every `@wix/*` vertical the page touches, including one added later:** confirmed the package is actually a dependency (installed it if not), and noted the Dev Center permission scope the read needs — a missing scope produces a page that builds, mounts and shows nothing. Both in [DATA_SOURCES.md](references/dashboard-page/DATA_SOURCES.md#two-things-to-settle-before-you-write-the-page); the scope goes under [Manual Steps Required](#-manual-steps-required). **A second vertical added during Step 4b needs this check too, and its failure must not take down the page** — see [A second vertical is a second scope](references/dashboard-page/DATA_SOURCES.md#a-second-vertical-is-a-second-scope).
- [ ] **Modelled the call on the SDK, not the REST page:** namespace name, `_id` vs `id`, no `ReturnType` on overloaded methods, no `hasNext` on `PagingMetadataV2` — see [The SDK is not the REST API](references/dashboard-page/DATA_SOURCES.md#the-sdk-is-not-the-rest-api).
- [ ] Site/editor extensions only: kept SDK calls in the extension by default, routing out only business-wide methods a visitor genuinely cannot call (see [Identity and Elevation Requirement](#identity-and-elevation-requirement))
- [ ] **Step 4a:** Scaffolded each CLI-supported extension via `wix generate --params`
- [ ] **Step 4b:** Filled in business logic in the generated files
- [ ] **Extension metadata (events, service plugins, data collections, dashboard pages, modals, dashboard plugins, dashboard menu plugins):** added the `name` and `aiContext` each scaffolded builder declares — see [EXTENSION_METADATA.md](references/EXTENSION_METADATA.md).
- [ ] **Compile as you go:** ran `npx tsc --noEmit` after the first file that imports `@wix/patterns`, not only at Step 5. Patterns' state and filter APIs are the most common source of errors, and finding twenty of them in one batch after the page is written costs far more than finding two early.
- [ ] **🛑 Component Selection Gate (MANDATORY, dashboard UI only):** For every UI element on a Dashboard Page, resolved it against `@wix/patterns` BEFORE reaching for `@wix/design-system` — and never hand-rolled a component either library already provides. See [Component Selection Order](#component-selection-order).
- [ ] 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.
- [ ] **Images:** display → [IMAGE_RENDERING.md](references/dashboard-page/IMAGE_RENDERING.md); editable entity fields → [IMAGE_EDITING.md](references/dashboard-page/IMAGE_EDITING.md).
- [ ] WDS: the design-system stylesheets are imported in exactly one place per app — `BusinessManagerTheme.tsx` for a dashboard surface (see the next item), or the main component entry file for a site/editor extension. Never in child, tab or helper files, and never twice.
- [ ] **🛑 Business Manager theme (every dashboard surface — page, modal AND plugin):** wrote `BusinessManagerTheme.tsx` once (both stylesheets, including `themes/odeditor.global.css`, plus `WixDesignSystemProvider` → `WixDesignSystemIconThemeProvider` → `IconThemeProvider theme="odeditor"` → `WixDesignSystemDefaultPropsProvider`), and wrapped **each** extension's root in it — above `WixPatternsProvider` and above `CustomModalLayout`. Any extension that renders `WixPatternsProvider` also gets `BusinessManagerPatternsTheme.tsx`, written once per app, nested directly inside the theme wrapper and above `WixPatternsProvider`. Patterns switches its own Harmony layout on the `bmHarmonyTheme` experiment, which never reaches the iframe. Without the second wrapper, the toolbar keeps an outlined Filter button and a pill search on an otherwise themed page ([BUSINESS_MANAGER_PATTERNS.md](references/BUSINESS_MANAGER_PATTERNS.md)). Every extension is a separate iframe that inherits none of the redesign, so theming the page does nothing for a modal it opens or a plugin in a slot; each one needs its own wrapper. Also: every icon from `@wix/wix-ui-icons-common/lazy`, and `--wds-*` tokens or `skin`/`size` props rather than hardcoded colours, font sizes or inline `style` ([BUSINESS_MANAGER_TOKENS.md](references/BUSINESS_MANAGER_TOKENS.md) — note the theme rebases the `SP*` spacing unit from 6px to 4px). `tsc`, `wix build` and `wix preview` all pass on an unthemed surface — only looking at it catches this. See [BUSINESS_MANAGER_THEME.md](references/BUSINESS_MANAGER_THEME.md).
- [ ] **Step 4c (dashboard page UI only):** Re-opened and read the page file(s) just written — not recalled intent — and confirmed against the actual code: no `SummaryBar` unless the request asked for one, a routed drill-in (`navigateToEntityPage`) for every row and no `SidePanel` used as one, every declared filter name also appearing inside `fetchData`, and — for every template with a router — the entry file both passes and guards `location`. See [UX Completeness Self-Audit](#step-4c-ux-completeness-self-audit).
- [ ] **Step 5:** Ran validation (see [Validation](#validation))
- [ ] Dependencies installed
- [ ] TypeScript compiled
- [ ] Build succeeded
- [ ] Preview deployed
- [ ] **Step 6:** Collected and presented ALL manual action items to user
**🛑 STOP:** If any box is unchecked, do NOT proceed to the next step.
---
## Quick Decision Helper
1. **What are you trying to build?**
- Admin interface → Dashboard Extensions
- Backend logic → Backend Extensions
- Data storage / CMS collections → Data Collection (app-owned data only — see [SDK-First Rule](#sdk-first-rule-existing-wix-app-data-is-never-cms))
- Editor React component → Site Extensions (app projects only)
2. **Who will see it?**
- Admin users only → Dashboard Extensions
- Site visitors → Site Extensions
- Server-side only → Backend Extensions
3. **Where will it appear?**
- Dashboard sidebar/page →
- Full admin screen: Dashboard Page — UI built with `@wix/patterns` + `@wix/design-system` (see [Component Selection Order](#component-selection-order)). **Cannot use `<Modal />`** — use a separate Dashboard Modal extension and `dashboard.openModal()` instead.
- Popup/form: Dashboard Modal
- Existing Wix app dashboard (widget) → Dashboard Plugin
- Existing Wix app dashboard (menu item, more-actions/bulk-actions menu) → Dashboard Menu Plugin
- Anywhere on site, standalone → custom element widget
- Anywhere on site, with editor manifest (styling/content/elements) → Editor React component
- Logic or shared state attached to an element already on the page (named, not asked to be created), or exposed to Editor Binding → Context Provider (wins over Editor React component when the element already exists)
- Code that runs once when one named page renders (page view event, UTM capture, A/B exposure) → Page onLoad (a context provider with no API); on every or any page, including future ones → Embedded Script
- Reusable functions the editor can call (formatters, helpers, event handlers) → Function Library
- Code that opens, closes or passes data to a popup → Lightbox rules, applied to the extension that renders on the site (usually a context provider)
- Fixed slot on a Wix business solution page → Site Plugin
- Scripts/analytics only, no UI → Embedded Script
- During business flow (checkout/shipping/tax) → Service Plugin
- Exposing tools to the Wix AI assistant → App Tools (requires both `APP_TOOLS` declaration + `TOOLS_PROVIDER_CONFIG` handler — see [APP_TOOLS.md](references/APP_TOOLS.md))
- After event occurs (webhooks/sync) → Backend Event Extension
- Custom HTTP endpoint → Backend API
---
## Component Selection Order
Dashboard UI comes from two libraries, resolved in this order. **Read [COMPONENT_SELECTION.md](references/dashboard-page/COMPONENT_SELECTION.md) before choosing any component.**
1. **`@wix/patterns`**: the page shell and everything collection-shaped (tables, filters, search, row and bulk actions, overlays, the page for one item). Look it up with `patterns-lookup.cjs` ([WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md)); never assemble it from WDS parts.
2. **`@wix/design-system`**: leaf-level UI patterns does not own (inputs, buttons, form fields, text, layout, cards, badges, tooltips, toasts, icons). Use the `wix-design-system` skill; only if it is missing, read the installed package's types and name the file.
3. **Custom React** only after both came back empty, composed from WDS layout primitives. No third UI dependency.
Never skip a step, and never decide a component is missing from memory: check. **Skipping to step 2 because a lookup was inconvenient is the most common way a dashboard page ends up all-WDS.**
**Overlaps:** in a patterns page, patterns' header and container win over WDS's. `PickerModal`, `usePickerModal` and `bulkActionModal` are patterns overlays, not WDS modals. Dashboard Plugins render outside a patterns shell, so WDS is the default there; patterns collection components still apply if the surface displays a data collection.
### Entity create and edit
Opening a listed record, and any create or edit form for one (even a single field), is an editable `EntityPage`, **not** a Dashboard Modal or `SidePanel`; "I built the list without `@wix/patterns`" is no exception. A page that lists nothing (settings, config) has no `EntityPage` obligation. A Dashboard Modal is only for dialogs that neither write nor display a listed record. On the create route, omit `entity` and read the Create route section of `<pkgRoot>/dist/docs/useEntityPage.md`. Full flow: [COMPONENT_SELECTION.md](references/dashboard-page/COMPONENT_SELECTION.md#entity-create-and-edit).
---
## Extension Types Reference Table
| Extension Type | Category | `extensionType` (for `wix generate --params`) | Reference File |
| --- | --- | --- | --- |
| Dashboard Page | Dashboard | `DASHBOARD_PAGE` | [DASHBOARD_PAGE.md](references/DASHBOARD_PAGE.md) |
| Dashboard Modal | Dashboard | `DASHBOARD_MODAL` | [DASHBOARD_MODAL.md](references/DASHBOARD_MODAL.md) |
| Dashboard Plugin | Dashboard | `DASHBOARD_PLUGIN` | [DASHBOARD_PLUGIN.md](references/DASHBOARD_PLUGIN.md) |
| Dashboard Menu Plugin | Dashboard | `DASHBOARD_MENU_PLUGIN` | [DASHBOARD_MENU_PLUGIN.md](references/DASHBOARD_MENU_PLUGIN.md) |
| Service Plugin | Backend | `SERVICE_PLUGIN` | [SERVICE_PLUGIN.md](references/SERVICE_PLUGIN.md) |
| App Tools (AI assistant tools) | Backend | `APP_TOOLS`, then `SERVICE_PLUGIN` with `pluginType: TOOLS_PROVIDER_CONFIG` | [APP_TOOLS.md](references/APP_TOOLS.md) |
| Backend Event Extension | Backend | `EVENT` | [BACKEND_EVENT.md](references/BACKEND_EVENT.md) |
| Backend API (HTTP endpoint) | Backend | `HTTP_ENDPOINT` | [BACKEND_API.md](references/BACKEND_API.md) |
| Data Collection | Backend | `DATA_COLLECTION` | [DATA_COLLECTION.md](references/DATA_COLLECTION.md) |
| Editor React component | Site | `EDITOR_REACT_COMPONENT` | [EDITOR_REACT_COMPONENT.md](references/EDITOR_REACT_COMPONENT.md) |
| Custom element widget | Site | `CUSTOM_ELEMENT` | [CUSTOM_ELEMENT_WIDGET.md](references/CUSTOM_ELEMENT_WIDGET.md) |
| Site Plugin | Site | `SITE_PLUGIN` | [SITE_PLUGIN.md](references/SITE_PLUGIN.md) |
| Embedded Script | Site | `EMBEDDED_SCRIPT` | [EMBEDDED_SCRIPT.md](references/EMBEDDED_SCRIPT.md) |
| Context Provider | Site | `CONTEXT_PROVIDER` | [CONTEXT_PROVIDER.md](references/CONTEXT_PROVIDER.md) |
| Function Library | Site | `FUNCTION_LIBRARY` | [FUNCTION_LIBRARY.md](references/FUNCTION_LIBRARY.md) |
| Page onLoad (a context provider with no API) | Site | `CONTEXT_PROVIDER`, named `Page On Load <Task Name>` | [PAGE_ON_LOAD.md](references/PAGE_ON_LOAD.md) |
| Lightbox (popup) open, close and data | Site | rules added to the extension that renders on the site | [LIGHTBOX.md](references/LIGHTBOX.md) |
**Key constraints:**
- Context Provider, Function Library, Page onLoad and Lightbox are for the Studio 2 editor only; they do not run on Harmony, classic Wix Editor or Wix Studio sites.
- Dashboard Page cannot use `<Modal />`; use a separate Dashboard Modal and `dashboard.openModal()`.
- A prompt that attaches logic to an element it names as already on the page ("hide Heading 1 on click", "show the footer text only after…") is a Context Provider consumed by Editor Binding, not a new Editor React component.
- A page onLoad context covers only the pages it is bound to; "whichever page", "any page" or "every page" means an Embedded Script instead.
- A popup that only opens automatically on page load, on chosen pages after a fixed delay, is the popup's auto-open setting in the editor, not code.
> **HTTP endpoints:** use `extensionType: "HTTP_ENDPOINT"` (not `BACKEND_API`); directories, handler types and frontend URLs are in [BACKEND_API.md](references/BACKEND_API.md).
## Cross-Cutting References
| Topic | Reference |
| --- | --- |
| Code Quality Requirements (applies to all generated code) | [CODE_QUALITY.md](references/CODE_QUALITY.md) |
| Extension Registration | [EXTENSION_REGISTRATION.md](references/EXTENSION_REGISTRATION.md) |
| Extension metadata — the `name` and `aiContext` to add to each scaffolded builder | [EXTENSION_METADATA.md](references/EXTENSION_METADATA.md) |
| App Validation | [APP_VALIDATION.md](references/APP_VALIDATION.md) |
| App Market Review | [APP_MARKET_REVIEW.md](references/APP_MARKET_REVIEW.md) |
| App Identifiers (Namespace, Code ID) | [APP_IDENTIFIERS.md](references/APP_IDENTIFIERS.md) |
| Wix Stores Versioning (V1/V3), including product media writes | [STORES_VERSIONING.md](references/STORES_VERSIONING.md) |
| Official Documentation Links | [DOCUMENTATION.md](references/DOCUMENTATION.md) |
| Wix Patterns Dashboard Pages | [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md) |
| Business Manager theme — the wrapper every dashboard page, modal and plugin needs | [BUSINESS_MANAGER_THEME.md](references/BUSINESS_MANAGER_THEME.md) |
| Business Manager tokens — `--wds-*` replacements, the rebased spacing unit, per-component adjustments | [BUSINESS_MANAGER_TOKENS.md](references/BUSINESS_MANAGER_TOKENS.md) |
| Business Manager theme for `@wix/patterns` — the second wrapper that turns on the patterns shell's Harmony layout | [BUSINESS_MANAGER_PATTERNS.md](references/BUSINESS_MANAGER_PATTERNS.md) |
| Dashboard UX Success Model (what a good dashboard contains) | [UX_SUCCESS_MODEL.md](references/dashboard-page/UX_SUCCESS_MODEL.md) |
| Draft template — start here for any dashboard page: finding, copying and adapting the package's page templates | [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md) |
| The state object `useTableCollection()` returns | [TABLE_STATE.md](references/dashboard-page/TABLE_STATE.md) |
| Finding the SDK method and field names behind a page | [DATA_SOURCES.md](references/dashboard-page/DATA_SOURCES.md) |
| Display images from CMS, vertical SDKs, and custom collections | [IMAGE_RENDERING.md](references/dashboard-page/IMAGE_RENDERING.md) |
| Edit entity images with Media Manager; draft, Save/Cancel, and picker verification | [IMAGE_EDITING.md](references/dashboard-page/IMAGE_EDITING.md) |
| Filter paths, WQL operators and cursor paging | [QUERY_AND_PAGING.md](references/dashboard-page/QUERY_AND_PAGING.md) |
---
## SDK-First Rule (Existing Wix App Data Is Never CMS)
**CRITICAL:** Data owned by an existing Wix business app is read and written through that app's SDK module — NEVER modeled as a new CMS Data Collection. A custom collection for such data starts empty and stays disconnected from the real records (e.g., a "refunds dashboard" built on CMS shows an empty state while refunded orders exist in Wix eCommerce).
Find the entity the user mentioned in the [entity → SDK module map](references/SDK_MODULE_MAP.md) and use that package; the [SDK lookup](#sdk-lookup-one-call-for-every-vertical-entity) then names the namespace and method. If the entity isn't listed and the lookup finds nothing, run `SearchWixSDKDocumentation` for it — **never conclude CMS without one of the two**. CMS is only for data your app itself introduces (configuration, rules, app-specific records) that no Wix app manages.
**SDK types:** access them through the namespace you import, as `<namespace>.<TypeName>`, using any type name shown in the docs — never import a type by name from the `@wix/<pkg>` root.
```ts
import { orders } from '@wix/ecom';
const rows: orders.Order[] = []; // ✅
// import type { Order } from '@wix/ecom'; // ❌ has no exported member 'Order'
```
**A map keyed by an SDK enum:** fields are typed `<Enum>WithLiterals` (the enum or its string values). `Partial<Record<bookings.BookingStatusWithLiterals, V>>` cannot be indexed by a status (TS7053). Use `Record<…WithLiterals, V>` with an entry for every value, or key a partial map by the string values: `` Partial<Record<`${bookings.BookingStatus}`, V>> ``.
---
## Data Collection Inference
**CRITICAL:** Data collections are often needed implicitly — don't wait for the user to explicitly say "create a CMS collection." Infer the need automatically.
**⚠️ Apply the [SDK-First Rule](#sdk-first-rule-existing-wix-app-data-is-never-cms) first** — the indicators below only apply to data your app itself owns, not to entities a Wix app already manages.
**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](#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](references/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:
1. **Get the app namespace** (see App Namespace Requirement above)
2. **Determine the `idSuffix`** for each collection (the Data Collection reference documents the full ID format)
3. **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.):
1. **Read the Stores Versioning reference** — see [STORES_VERSIONING.md](references/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%.
2. **All Stores operations must check catalog version first** using `getCatalogVersion()`
3. **Use the correct module** based on version: `productsV3` (V3) vs `products` (V1)
4. **Apps MUST support both V1 and V3** — single-version apps cannot list in the App Market and break on new sites
5. **Request both V1 and V3 permission scopes** for every Stores operation
This is non-negotiable — V1 and V3 are NOT backwards compatible.
---
## Identity and Elevation Requirement
**Applies whenever an extension calls a Wix SDK method.** Decide where the call runs before writing it.
Who the extension runs as decides everything below — the Category column in [Extension Types Reference Table](#extension-types-reference-table) tells you which one you have:
- **Site and editor extensions** — custom element widgets, site plugins, Editor React components, embedded scripts — run as the site visitor or member, never as the app.
- **Dashboard extensions** run as the Wix user — not as a site visitor, and not as the app.
- **Backend extensions** — Backend API, Backend Event, Service Plugin — run as the app.
**`auth.elevate` works only in backend code.** In a site, editor, or dashboard extension it doesn't work at all.
**Default: call the SDK directly from the extension.** Routing a call that didn't need it is not a harmless extra hop — it is how working features break. Sort by who the call acts for, never by its scope name:
- **Acts for the current visitor or member** — their cart, checkout, booking, order, reservation, or profile: `currentCartV2.*`, `cartV2.placeOrder...
© wix · MIT · wix/skills