Wix App

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:

• Not done: Step 1: Determined extension type(s) needed
  • Not done: Asked clarifying questions if requirements were unclear
  • Not done: 🛑 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)
  • Not done: Checked for implicit Data Collection need — unless user provided a collection ID directly (see Data Collection Inference)
  • Not done: Obtained app namespace if Data Collection extension is being created
  • Not done: Determined full scoped collection IDs if Data Collection extension is being created (see Collection ID Coordination)
  • Not done: Explained recommendation with reasoning
• Not done: Step 2: Read extension reference file(s) for the chosen type(s) and the project-wide CODE_QUALITY.md (opens in a new tab)

  • Not done: 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 (opens in a new tab), and the installed package’s own Collection Toolkit.md guide for which component serves each need (The Discovery Chain (opens in a new tab)).

    • Not done: 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 (opens in a new tab)) and be read through useSelector, because the state is MobX (TABLE_STATE.md (opens in a new tab)).
    • Not done: 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 (opens in a new tab). Unless the prompt is explicitly a report or an export. Never a SidePanel: in Cairo that hosts a page’s own panels.
    • Not done: 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.

  • Not done: 🛑 Template-First Gate (MANDATORY, dashboard UI only, comes before writing any shell/provider/router): Followed DRAFT_TEMPLATE.md (opens in a new tab): 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.

  • Not done: 🛑 Patterns Docs Gate (MANDATORY for any dashboard page UI): Read WIX_PATTERNS_DOCS.md (opens in a new tab) 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).

  • Not done: 🛑 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 (opens in a new tab). 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 (opens in a new tab) — a state object you receive rather than construct, whose members are unobvious and several plausible ones absent.

• Not done: Step 3: Checked API references; resolved every vertical entity in one sdk-lookup.cjs call (SDK lookup); used the docs only for what it does not print
  • Not done: 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 (opens in a new tab), and QUERY_AND_PAGING.md (opens in a new tab) before writing fetchData. A field marked @deprecated still compiles and renders something plausible and wrong.
  • Not done: 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 (opens in a new tab); the scope goes under 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 (opens in a new tab).
  • Not done: 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 (opens in a new tab).
  • Not done: 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)
• Not done: Step 4a: Scaffolded each CLI-supported extension via wix generate --params
• Not done: Step 4b: Filled in business logic in the generated files
  • Not done: 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 (opens in a new tab).
  • Not done: 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.
  • Not done: 🛑 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.
  • Not done: 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.
  • Not done: Images: display → IMAGE_RENDERING.md (opens in a new tab); editable entity fields → IMAGE_EDITING.md (opens in a new tab).
  • Not done: 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.
  • Not done: 🛑 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 (opens in a new tab)). 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 (opens in a new tab) — 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 (opens in a new tab).
• Not done: 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.
• Not done: Step 5: Ran validation (see Validation)
  • Not done: Dependencies installed
  • Not done: TypeScript compiled
  • Not done: Build succeeded
  • Not done: Preview deployed
• Not done: 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)
   • 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). 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 (opens in a new tab))
   • 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 (opens in a new tab) 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 (opens in a new tab)); 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 (opens in a new tab).

Extension Types Reference Table

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 (opens in a new tab).

Cross-Cutting References

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 (opens in a new tab) and use that package; the SDK lookup 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.

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 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:

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 (opens in a new tab) 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 (opens in a new tab). 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 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, bookings.createBooking, members.getCurrentMember (REST Get My Member), and anything else operating on “my” or “the current” entity. These resolve the actor from the caller’s session, so elevating runs them as the app and detaches the result from the person who asked — an order with no buyer, a booking with no attendee.
• The platform filters the result by caller — an elevated call returns what the direct call withheld, so a “fix” for a sparse result becomes a leak. Wix Data items.* follows the collection’s dataPermissions (scaffolded default: itemRead: 'ANYONE', writes 'PRIVILEGED' — fix writes with permissions, not routing; see DATA_COLLECTION.md (opens in a new tab)). Catalog reads return base fields to anyone, withholding MERCHANT_DATA and non-visible products unless the app holds SCOPE.STORES.PRODUCT_READ_ADMIN. members.getMember/queryMembers withhold PRIVATE members from visitor and member callers.

Route out only when the method acts on the business as a whole, which a visitor or member genuinely cannot do: archiveLocation, queryLocations, catalog and inventory writes, bookings.confirmBooking, order management. When the method’s docs show the call elevated, route it out and elevate there — from any host, dashboard included, because auth.elevate only works in backend code, so the endpoint is the only place the documented pattern can run.

When you’re unsure in a site, editor, or dashboard extension, call it directly and let it fail. A method a site extension may not call returns a permission error you see immediately; a method wrongly routed and elevated succeeds and silently returns the wrong data or acts for the wrong person. Some method pages carry a prose note that settles it — get-my-member: “This method requires visitor or member authentication.” Authoritative when present (the SDK lookup prints it as the method’s note), but only a minority of pages have one, so its absence decides nothing.

Two signals never settle it: the scope name — the methods whose scope name points the wrong way are rules in sdk-curated.json (opens in a new tab), which the SDK lookup prints as note — and the SDK schema line’s client prefix, which varies by docs channel for the same method, so carries nothing and isn’t worth re-deriving.

Routing out means a Backend API endpoint that elevates and is reached with httpClient.fetchWithAuth(). Elevation bypasses Wix’s permission check, so the endpoint must re-check the caller itself — see Identity and Authorization (opens in a new tab) for what each host can actually verify, and why an owner-only operation belongs in a dashboard extension instead.

Some extensions or SDK calls require a permission scope that wix generate doesn’t add automatically. Adding one is a Dev Center account change, not something the agent does — tell the user which scope to add: open their app at https://manage.wix.com/apps/<appId>/home, select Develop > Permissions in the left menu, then Add Permissions, then report it under Manual Steps Required. If the app is already installed on a site, the owner must also re-approve it via the install/update flow — revisit that same app page’s “Test App” flow (or the release output’s install links) and accept “Agree & Update” — before the scope takes effect there.

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 (opens in a new tab) — 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 → SDK lookup for vertical entities → docs only for what the lookup does not print.

1. Read the extension reference file for the chosen extension type from the table above
2. Identify required APIs from user requirements
3. Check relevant API reference files:
   • Backend events → references/backend-event/COMMON-EVENTS.md
   • Wix Data → references/data-collection/WIX_DATA.md
   • Dashboard SDK → references/dashboard-page/DASHBOARD_API.md; Media Manager → references/dashboard-page/DASHBOARD_API_MEDIA_AND_PLUGINS.md
   • Service Plugin SPIs → read references/SERVICE_PLUGIN.md, then the SPI file its References table links
   • App Tools (AI assistant tools) → read references/APP_TOOLS.md; it links to references/app-tools/TOOLS.md (declaration) and references/service-plugin/TOOLS_PROVIDER.md (handler)
4. Verify the specific method/event exists in references
5. For vertical entities, run the SDK lookup once, with every entity; use MCP discovery only for what neither the references nor the lookup answer

Platform APIs (never discover - in references):

• Wix Data, Dashboard SDK, Event SDK (common events), Service Plugin SPIs

Vertical APIs (discover if needed):

• Wix Stores (⚠️ MUST use Stores Versioning reference — V1/V3 catalog check required), Wix eCommerce, Wix Bookings, Wix Members, Wix Pricing Plans, third-party integrations — find the right @wix/* package in the SDK-First Rule module map first, install it, then get the namespace and method from the SDK lookup

Decision table:

SDK lookup: one call for every vertical entity

node <this-skill-dir>/scripts/sdk-lookup.cjs contacts orders --intent search   # search | read | write | event | all

Run it from the app directory, after the vertical packages are installed, with every entity the feature touches in one call. Pick the intent from the feature, once. A dashboard collection page edits its records by default (DRAFT_TEMPLATE.md (opens in a new tab)), so it uses all: that holds the search and write lines, the search methods first. Use search (with a search box) or read only for a read-only page, and write for a feature that only writes. Do not pipe the output through head. Per entity it prints:

• the namespace to use and why (a curated rule; within one package, a search* method for a search, then the highest API version; across packages that export the same name, the module map’s package, else the package named after it), and the other namespaces — across packages, each with its entity description, so switch when the feature matches another one;
• the import line;
• shape: the one call to write for the intent, with its reason and, for a search, where the term goes;
• each method for the intent, with its call shape (search, query-builder, query, …), permission, required fields (revision) and its docs notes (note, with an update’s field rules: what a missing field does, and how to clear one); limits, the size and range caps its request declares (orderIds 1–100 items, limit() ≤1000): keep a page limit within the cap of a batch method it feeds; fieldsets when an option decides which fields come back (members default to PUBLIC, without loginEmail or contact: ask for the set that holds every field you show); for a search, query or list method also arg and returns, the keys of its argument (cursorPaging, filter, sort, search) and of its response (pagingMetadata.cursors.next); a filter list only when the package declares one (otherwise the method docs page lists the fields) — not who may call it: that stays with Identity and Elevation Requirement;
• the entity type as file:line — the declaration to verify fields against (DATA_SOURCES.md (opens in a new tab));
• each method’s own declaration as decl file:line — read the types behind arg and returns there, not by searching the typings;
• the curated rules for the entity (note), such as the Stores V1/V3 check.

Take the namespace, the method and the call shape from its output; do not re-derive them from the typings, and follow the lines under shape. When the lookup prints site, the choice depends on the site (Stores: call getCatalogVersion() and support both). not installed prints the install command: install, then run the lookup again. A name it does not know exits 1 with near matches.

It prints each search and query method’s closed filter list (free-text fields, operators per field, sort) from the package’s own declarations. It prints a method’s permission scope ID only when the package declares it; when the output says scope: not in the package, get the scope from the method’s docs page (the next list).

MCP Tools for discovery (for what the lookup does not print):

• 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 supported type, including HTTP endpoints, 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. The one exception is HTTP_ENDPOINT on a CLI older than 1.1.243, which predates the generator but still supports the extension: create the endpoint file by hand as described in BACKEND_API.md (opens in a new tab).

What the CLI does automatically:

• Creates folders and stub files
• For registered extensions, generates a fresh UUID and updates src/extensions.ts with the import and .use() call
• For HTTP endpoints, creates the route file without changing src/extensions.ts
• Enforces naming rules (kebab-case, hyphen-required custom elements, etc.)

HTTP endpoints: Run npx wix generate --params '{"extensionType":"HTTP_ENDPOINT","name":"hello"}', then implement the handler in the returned file. Follow BACKEND_API.md (opens in a new tab); if the route does not respond, its troubleshooting hint shows how to confirm discovery from the build output.

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.
• Events, service plugins, data collections, and dashboard pages, modals, dashboard plugins and dashboard menu plugins: finish each *.extension.ts with the name and aiContext its builder declares, per EXTENSION_METADATA.md (opens in a new tab).
• ⚠️ 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 4c: UX Completeness Self-Audit

Dashboard page UI only. tsc, wix build, and wix preview all check that the code compiles and runs — none of them check that it’s the dashboard the UX Success Model (opens in a new tab) describes. A page with a bare, un-summarized, un-openable table compiles cleanly and still fails the requirement — that gap is exactly how a generated dashboard passes every technical check and still disappoints. Measured runs confirm it: a page can compile clean and still ship with none of the three items below, because the earlier checklist entries were a stated intention rather than something re-checked against the code that actually landed.

Before moving to Step 5, re-open every page file you just wrote and check the actual code — not what you intended to include:

• Not done: The page has a SummaryBar only if the request asked for one. Grep for it: an uninvited bar is a defect, not a bonus, and deleting it is the fix. If the request did ask, every metric earns its place and the headline counts what matches the filters (state.collection.total, fed by fetchTotal), not what has been paged in — any metric derived from keyedItems is labelled as such.

• Not done: If a SummaryBar number is fed by fetchTotal, follow that function to the call it makes and confirm the call counts. A fetchTotal that resolves undefined — the usual cause being pagingMetadata.total, which a cursor-paged response does not carry — makes the bar report 0 beside a table full of rows, and it compiles, runs and passes every other check on this list. It must resolve a number from a count endpoint (items.query(id)…count(), a vertical’s own count, or offset paging with returnTotalCount: true); if the API has none, delete fetchTotal and label the metric as loaded rows. See TABLE_STATE.md (opens in a new tab).

• Not done: Every row opens an editable entity page by default: onRowClick calls navigateToEntityPage, and the destination has an EntityPage, a working form, and a real save operation. A read-only route is justified by one of the three cases in DRAFT_TEMPLATE.md (opens in a new tab), and the final response names which one; report-only/export-only requests need no drill-in. The save calls the source’s real update method and lets a failed call throw, so the page shows its error — no no-op, local-state-only save, or catch that swallows the failure. If Preview is available, change one field, reload to confirm it saved, and change it back; otherwise report the save as unverified. A SidePanel in a collection page file is the defect this replaces. grep -n "<SidePanel" <page files> should return nothing — match the JSX tag, not the bare word, or the templates’ own “never a SidePanel” comments fail the check and invite someone to “fix” correct code.

• Not done: Every filter name declared in the toolbar also appears inside fetchData‘s query construction — grep for the name in both places if unsure.

• Not done: The table wires errorState — without it a failed query is indistinguishable from a slow one, and the page you just shipped cannot tell you which it is.

• Not done: Routed templates only (all but the settings one) — the entry file both passes and guards location. PatternsReactRouter throws at open when location is missing or still undefined on the first render, and tsc, wix build and even a green build all pass regardless. Both halves are required — the location={location} prop and the location ? … : null guard around it, since observeState has not fired yet on the first render. Grep the entry file rather than trusting recall:

  bashCopy

  grep -n "observeState\|location={location}\|location ?" src/extensions/dashboard/pages/<page>/<page>.tsx  # the file the builder's `component` points at

  Three hits is correct. A missing guard is the failure mode that has actually shipped: a measured run produced a page whose plumbing looked present and still crashed on open, while a re-run of the same prompt produced a working one — so this is intermittent, and re-running is not a check.

• Not done: Every @wix/* vertical imported by the page’s api module is a declared dependency, and each one’s scope is listed under Manual Steps. Any call to a secondary vertical (an enrichment lookup, a filter’s options, a search term resolved to ids) is wrapped so its failure degrades that feature instead of failing the page.

If a box fails and no exception applies, add the missing piece now. Do not let “it compiles” stand in for “it satisfies the checklist” — Step 5 checks the former, this step checks the latter, and they are independent.

Step 5: Run Validation

Run the four steps in Validation below. Do NOT report completion to the user until validation passes — if it fails, fix the errors and re-validate until it does.

Step 6: Report Completion

Only after validation passes, provide a concise summary section at the top of your response:

## ✅ Implementation Complete

[1-2 sentence description of what was built]

**Extensions Created:**
- [Extension 1 Name] - [Brief purpose]
- [Extension 2 Name] - [Brief purpose]

**Build Status:**
- ✅ Dependencies: [Installed / status message]
- ✅ TypeScript: [No compilation errors / status]
- ✅ Build: [Completed successfully / status]
- ✅/⚠️ Preview: [Created — Dashboard URL / Failed - reason]

**⚠️ IMPORTANT: [X] manual step(s) required to complete setup** (see "Manual Steps Required" section below)

• 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 registered extensions. HTTP endpoints require no import or .use() call; the runtime discovers their files. For background, troubleshooting, and the manual recovery pattern when src/extensions.ts drifts, see EXTENSION_REGISTRATION.md (opens in a new tab).

Validation

Execute these steps sequentially after all implementation is complete. See APP_VALIDATION.md (opens in a new tab) for the complete guide. Dashboard page UI: run Step 4c’s UX Completeness Self-Audit first — the checks below verify the code runs, not that it’s the dashboard the prompt asked for.

1. Package Installation — Detect package manager, run install
2. TypeScript Compilation — npx tsc --noEmit -p .
3. Build — npx wix build
4. Preview — npx wix preview, in the foreground and unpiped: it uploads, prints the preview URLs and exits on its own, so no timeout, backgrounding, sleep or | tail. If your shell moves it to the background anyway, it stalled: read what it printed and .wix/debug.log once, then report that the preview did not complete. Don’t poll, and don’t promise a URL

Stop and report errors if any step fails. Check .wix/debug.log on failures.

Documentation

For links to official Wix CLI documentation for all extension types, see DOCUMENTATION.md (opens in a new tab).