Terminal
Terminal/Skill
Helps build and review Wix CLI app extensions, such as dashboard pages, widgets, backend APIs, and App Market submissions.
By Wix
Works with
npx skills add wix/skills --skill wix-appHelps 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. 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.
Before reporting completion to the user, ALL boxes MUST be checked:
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, and the installed package's own Collection Toolkit.md guide for which component serves each need (The Discovery Chain).
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) and be read through useSelector, because the state is MobX (TABLE_STATE.md).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. Unless the prompt is explicitly a report or an export. Never a SidePanel: in Cairo that hosts a page's own panels.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: 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 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, per Component Selection Order's "the short version". 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 — a state object you receive rather than construct, whose members are unobvious and several plausible ones absent.
fetchData. A field marked @deprecated still compiles and renders something plausible and wrong.@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; 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._id vs id, no ReturnType on overloaded methods, no hasNext on PagingMetadataV2 — see The SDK is not the REST API.wix generate --paramsnpx 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.@wix/patterns BEFORE reaching for @wix/design-system — and never hand-rolled a component either library already provides. See Component Selection Order.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.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.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. 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 — 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.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.🛑 STOP: If any box is unchecked, do NOT proceed to the next step.
What are you trying to build?
Who will see it?
Where will it appear?
@wix/patterns + @wix/design-system (see Component Selection Order). Cannot use <Modal /> — use a separate Dashboard Modal extension and dashboard.openModal() instead.APP_TOOLS declaration + TOOLS_PROVIDER_CONFIG handler — see APP_TOOLS.md)For the page shell, provider nesting, and routing — the part every dashboard page needs — start from DRAFT_TEMPLATE.md, not this section. It finds the page templates the installed @wix/patterns ships (read-only list, list with create/edit, settings only, and a CMS collection on its schema); copy the one the request matches and adapt it. What follows here is for individual UI elements the template doesn't already show — a filter type, a column renderer, a component the request needs that isn't in it.
Dashboard pages at Wix are built from two libraries. For every UI element not already covered by the template, resolve in this order and stop at the first hit. Never skip a step, and never decide a component is missing from memory — check.
@wix/patterns — page structure and data collectionsPatterns owns the page shell and everything collection-shaped: page shells and their header / content / footer sub-parts, tables and grids and the switch between them, folder views, collection state (paging, sorting, selection, loading), filters, search, view presets, row and bulk actions, drag-and-drop, in-extension routing, the overlays tied to a collection, and the add / edit / view page for one listed item. If you need one of those, it is patterns' — look it up rather than assembling it from WDS parts.
Which component serves a given need is the library's own answer, not this skill's. It ships that answer as guides inside the installed package, with every component name in them checked against the real package at build time. Walk them: The Discovery Chain.
Whole pages are the package's too: the router wiring for a multi-page extension, and a
collection whose fields the CMS owns — useCmsSchemaSource from @wix/patterns-cms, with
@wix/patterns/schema, where the schema supplies fetch, filters, columns and the form — both ship
as page templates. See DRAFT_TEMPLATE.md.
The short version: list every patterns name you plan to write, and resolve them all in one
node <pkgRoot>/bin/patterns-lookup.cjs <name…> call, not one index probe per name.
Its output gives each name's import line (no read needed), its worked examples, and the one
file that holds its props. Read the one artifact your open question needs. Resolve <pkgRoot> once per session
(Prerequisites) and reuse it.
Opening one item from a collection uses an editable EntityPage by default; create/edit flows also use EntityPage, never a dashboard modal — see
Entity create and edit, and Collection to Entity Flow.md in the
package for the flow itself.
Falling through to step 2 because a lookup was inconvenient is the single most common way a dashboard page ends up built entirely from WDS. A missing index means the lookup has not happened yet, not that patterns lacks the component.
@wix/design-system — everything inside the shellThe leaf-level UI patterns does not own: inputs, buttons, form fields, text, layout primitives, cards, badges, tooltips, toasts, icons. Pick the component by lookup, not recall — invoke the wix-design-system skill, whose bundled helper reads the installed package:
node <wix-design-system-skill-dir>/scripts/wds.cjs search <keyword>
node <wix-design-system-skill-dir>/scripts/wds.cjs component <Name>
If that skill is not installed — it is a separate skill, and some hosts ship wix-app without
it — do not fall through to writing WDS from memory, and do not treat the missing skill as
permission to hand-roll the component. Read the installed package instead, which is where the skill
would have read from anyway:
ls node_modules/@wix/design-system/dist/types/ # the component inventory
cat node_modules/@wix/design-system/dist/types/<Name>/<Name>.d.ts # its real props
Name the file you read before using the component, exactly as the Component Docs Gate requires for patterns. A missing skill lowers the convenience, not the bar.
Compose from WDS layout primitives (Box, Card, Text). Do not add a third UI dependency, and do not restyle patterns or WDS internals.
PickerModal / usePickerModal and bulkActionModal cover collection-related overlays. "It's a modal" is not a reason to leave patterns.Opening a record listed by a collection page uses an editable EntityPage by default, whether the records come from CMS or a vertical SDK. A request for a table or list is enough; the user does not need to ask for editing separately. The three read-only cases are in DRAFT_TEMPLATE.md; a read-only detail page still opens as a route, never a Dashboard Modal or side panel.
Any create or edit form for a listed record is an EntityPage, not a Dashboard Modal. A create / "add new" form is included: it writes the record, so it is an EntityPage even though nothing is being edited yet. "It's a simple data-entry dialog, not an entity edit" is the wrong reading of this rule.
A page that lists nothing — a settings page, an embedded-script config page — carries no EntityPage obligation. But "I built the list without @wix/patterns" is not an exception: a page that lists records should be a CollectionPage.
This is the most common place the selection order gets dropped: the collection gets built correctly with patterns, then the "add item" flow is hand-built as a WDS form in a modal.
The documented flow:
navigateToEntityPage({ path, entity }) from usePatternsNavigate(). (The patterns docs give this exact use case — "navigate to an entity page on an action cell click on a collection page" — and it renders the entity header immediately, before the fetch resolves.) On the create route there is no record to pass: omit entity and read the Create route section of <pkgRoot>/dist/docs/useEntityPage.md, which is what the whole "add new" flow turns on.PatternsReactRoute inside PatternsReactRouter.useEntityPage({ fetch, onSave }) owns fetching, saving, validation, dirty state, loading skeletons, and error states; for CMS, the schema variant derives reads and writes from the source. Form state comes from @wix/patterns/form. Use the chosen template's documented signature, and wire saves to the real source rather than local state or a no-op.EntityPage.Header, EntityPage.MainContent, EntityPage.AdditionalContent, and EntityPage.Card. WDS goes inside those cards — FormField, Input, Text for the individual fields.Use a Dashboard Modal for dialogs that neither write nor display a listed record: a delete or discard confirmation, an unsaved-changes prompt, an informational notice, or any dialog on a page that lists nothing. Dialog size and field count are not exceptions — a one-field create form over a listed record is still an EntityPage. Reach for a modal because the interaction persists nothing, never because "the form should open in a modal."
| Extension Type | Category | extensionType (for wix generate --params) | Reference File |
|---|---|---|---|
| Dashboard Page | Dashboard | DASHBOARD_PAGE | DASHBOARD_PAGE.md |
| Dashboard Modal | Dashboard | DASHBOARD_MODAL | DASHBOARD_MODAL.md |
| Dashboard Plugin | Dashboard | DASHBOARD_PLUGIN | DASHBOARD_PLUGIN.md |
| Dashboard Menu Plugin | Dashboard | DASHBOARD_MENU_PLUGIN | DASHBOARD_MENU_PLUGIN.md |
| Service Plugin | Backend | SERVICE_PLUGIN | SERVICE_PLUGIN.md |
| App Tools (AI assistant tools) | Backend | APP_TOOLS, then SERVICE_PLUGIN with pluginType: TOOLS_PROVIDER_CONFIG | APP_TOOLS.md |
| Backend Event Extension | Backend | EVENT | BACKEND_EVENT.md |
| Backend API (HTTP endpoint) | Backend | HTTP_ENDPOINT | BACKEND_API.md |
| Data Collection | Backend | DATA_COLLECTION | DATA_COLLECTION.md |
| Editor React component | Site | EDITOR_REACT_COMPONENT | EDITOR_REACT_COMPONENT.md |
| Custom element widget | Site | CUSTOM_ELEMENT | CUSTOM_ELEMENT_WIDGET.md |
| Site Plugin | Site | SITE_PLUGIN | SITE_PLUGIN.md |
| Embedded Script | Site | EMBEDDED_SCRIPT | EMBEDDED_SCRIPT.md |
Key constraints:
<Modal />; use a separate Dashboard Modal and dashboard.openModal().HTTP endpoints: Generate with
extensionType: "HTTP_ENDPOINT"(notBACKEND_API). See BACKEND_API.md for project-specific directories, handler types, and frontend URLs.
| Topic | Reference |
|---|---|
| Code Quality Requirements (applies to all generated code) | CODE_QUALITY.md |
| Extension Registration | EXTENSION_REGISTRATION.md |
| App Validation | APP_VALIDATION.md |
| App Market Review | APP_MARKET_REVIEW.md |
| App Identifiers (Namespace, Code ID) | APP_IDENTIFIERS.md |
| Wix Stores Versioning (V1/V3) | STORES_VERSIONING.md |
| Official Documentation Links | DOCUMENTATION.md |
| Wix Patterns Dashboard Pages | WIX_PATTERNS_DOCS.md |
| Business Manager theme — the wrapper every dashboard page, modal and plugin needs | BUSINESS_MANAGER_THEME.md |
Business Manager tokens — --wds-* replacements, the rebased spacing unit, per-component adjustments | BUSINESS_MANAGER_TOKENS.md |
| Dashboard UX Success Model (what a good dashboard contains) | UX_SUCCESS_MODEL.md |
| Draft template — start here for any dashboard page: finding, copying and adapting the package's page templates | DRAFT_TEMPLATE.md |
The state object useTableCollection() returns | TABLE_STATE.md |
| Finding the SDK method and field names behind a page | DATA_SOURCES.md |
| Filter paths, WQL operators and cursor paging | QUERY_AND_PAGING.md |
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 and use that package. If the entity isn't listed or you're unsure, run SearchWixSDKDocumentation for it — never conclude CMS with zero MCP calls. 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'
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:
| 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.
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.
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:
idSuffix for each collection (the Data Collection reference documents the full ID format)<app-namespace>/<idSuffix>) in all extensions that reference the collection via Wix Data API callsApplies when ANY Wix Stores API is used (products, inventory, orders, etc.):
getCatalogVersion()productsV3 (V3) vs products (V1)This is non-negotiable — V1 and V3 are NOT backwards compatible.
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:
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:
currentCartV2.*, cartV2.placeOrder, bookings.createBooking, members.getMyMember, 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.items.* follows the collection's dataPermissions (scaffolded default: itemRead: 'ANYONE', writes 'PRIVILEGED' — fix writes with permissions, not routing; see DATA_COLLECTION.md). 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, 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, but only a minority of pages have one, so its absence decides nothing.
Two signals never settle it: the scope name — locations.queryLocations is SCOPE.DC-MULTILOCATION.READ-LOCATIONS yet admin-only, while currentCartV2.addLineItemsToCurrentCart carries SCOPE.ECOM.MANAGE-ADMIN yet is visitor-callable and breaks if elevated — 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 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.
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.
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.
Use the Extension Types Reference Table and decision content above. State extension type and brief reasoning (placement, functionality, integration).
Workflow: Read extension reference → Check API references → Use MCP only for gaps.
references/backend-event/COMMON-EVENTS.mdreferences/data-collection/WIX_DATA.mdreferences/dashboard-page/DASHBOARD_API.mdreferences/SERVICE_PLUGIN.md together with the matching references/service-plugin/<NAME>.md leafreferences/APP_TOOLS.md; it links to references/app-tools/TOOLS.md (declaration) and references/service-plugin/TOOLS_PROVIDER.md (handler)Platform APIs (never discover - in references):
Vertical APIs (discover if needed):
@wix/* package in the SDK-First Rule module map first, then discover methods via MCPDecision table:
| User Requirement | Check References / Discovery Needed? | Reason / Reference File |
|---|---|---|
| "Display store products" | ✅ YES (MCP discovery) | Wix Stores API — include Stores Versioning reference |
| "Dashboard for orders / refunds" | ✅ YES (MCP discovery) | Wix eCommerce API (@wix/ecom) — NEVER a CMS collection |
| "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)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.
What the CLI does automatically:
src/extensions.ts with the import and .use() callsrc/extensions.tsHTTP endpoints: Run npx wix generate --params '{"extensionType":"HTTP_ENDPOINT","name":"hello"}', then implement the handler in the returned file. Follow BACKEND_API.md; if the route does not respond, its troubleshooting hint shows how to confirm discovery from the build output.
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.
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.idSuffix (case-sensitive). If idSuffix is "product-recommendations", use <app-namespace>/product-recommendations NOT productRecommendations.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 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:
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.
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.
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, 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.
Every filter name declared in the toolbar also appears inside fetchData's query construction — grep for the name in both places if unsure.
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.
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:
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.
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.
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.
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)
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]
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.
Execute these steps sequentially after all implementation is complete. See APP_VALIDATION.md 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.
npx tsc --noEmit -p .npx wix buildnpx 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 URLStop and report errors if any step fails. Check .wix/debug.log on failures.
For links to official Wix CLI documentation for all extension types, see DOCUMENTATION.md.