From wix-cli
Use when building admin interfaces, management pages, CRUD operations, or dashboard configuration UIs. Triggers include dashboard, admin panel, data management, settings pages.
npx claudepluginhub wix-playground/skills-architecture-test --plugin wix-cliThis skill uses the workspace's default tool permissions.
Creates full-featured dashboard page extensions for Wix CLI applications. Dashboard pages appear in the Wix site owner's dashboard and enable site administrators to manage data, configure settings, and perform administrative tasks.
Builds and reviews Wix CLI app extensions: dashboard pages, modals, plugins, Editor React components, backend APIs, events, service plugins, data collections. Prepares apps for App Market review.
Generates FilamentPHP v4 dashboard pages with single-tab or multi-tab layouts, message callouts, and widget integration. Useful for admin panel dashboards.
Guides building SaaS dashboards, settings pages, data tables, and layouts with shadcn/ui + Tailwind. Covers component library selection, page composition, responsive design, dark mode, and UI states (loading, empty, error).
Share bugs, ideas, or general feedback.
Creates full-featured dashboard page extensions for Wix CLI applications. Dashboard pages appear in the Wix site owner's dashboard and enable site administrators to manage data, configure settings, and perform administrative tasks.
Follow these steps in order when creating a dashboard page:
src/extensions/dashboard/pages/<page-name>/page.tsx with WDS components wrapped in WixDesignSystemProviderextensions.ts with extensions.dashboardPage() and unique UUIDsrc/extensions.ts to import and use the new extensionSee Wix Data Reference for complete documentation.
Summary:
items.query('Collection').filter/sort.limit.find() → { items, totalCount, hasNext }items.insert | update | remove. Ensure collection permissions allow the actionQuery methods: eq, ne, gt, ge, lt, le, between, contains, startsWith, endsWith, hasSome, hasAll, isEmpty, isNotEmpty, and, or, not, ascending, descending, limit, skip, include
See Dashboard API Reference for complete documentation including all methods, page IDs, and examples.
Key methods:
dashboard.navigate() - Navigate between dashboard pagesdashboard.observeState() - Receive contextual state and environmental informationdashboard.showToast() - Display toast notificationsdashboard.openModal() - Open dashboard modal extensions (see wix-cli-dashboard-modal)dashboard.navigateBack() - Navigate back to previous pagedashboard.getPageUrl() - Get full URL for a dashboard pagedashboard.openMediaManager() - Open Wix Media Managerdashboard.onBeforeUnload() - Register beforeunload handlerdashboard.addSitePlugin() - Add site plugin to slotsdashboard.setPageTitle() - Set page title in browser tabdashboard.onLayerStateChange() - Handle foreground/background state changesCRITICAL: Using Modals in Dashboard Pages
When you need to display popup forms, confirmations, detail views, or any dialog overlays from a dashboard page, you MUST use dashboard modals, not regular React modals or WDS Modal components.
Modal component or custom React modal implementationsDashboard modals are opened using dashboard.openModal() and provide proper integration with the dashboard lifecycle, state management, and navigation.
Ecom Navigation: See Ecom Navigation Reference for ecom-specific navigation helpers.
When building a dashboard page to configure an embedded script, see Dynamic Parameters Reference for complete implementation guide.
Key points:
embeddedScripts from @wix/app-managementwithProviders wrapper when dynamic parameters are presentDashboard pages live under src/extensions/dashboard/pages. Each page has its own folder.
File structure:
src/extensions/dashboard/pages/<page>/page.tsx — page componentKey metadata fields:
id (string, GUID): Unique page ID used to register the pagetitle (string): Used for browser tab and optional sidebar labeladditionalRoutes (string[], optional): Extra routes leading to this pagesidebar.disabled (boolean, optional): Hide page from sidebar (default false)sidebar.priority (number, optional): Sidebar ordering; lower is higher prioritysidebar.whenActive.selectedPageId (string, optional): Which page appears selected when this page is activesidebar.whenActive.hideSidebar (boolean, optional): Hide sidebar when this page is activeWrap your dashboard page component with WixDesignSystemProvider to enable WDS components and theming. You must also import the global CSS styles for WDS components to render correctly.
import { WixDesignSystemProvider } from "@wix/design-system";
import '@wix/design-system/styles.global.css';
export default function () {
return (
<WixDesignSystemProvider>
<Page>
<Page.Header
title="My Page"
subtitle="This is a subtitle for your page"
/>
<Page.Content>
<EmptyState title="My Page" subtitle="Hello World!" theme="page" />
</Page.Content>
</Page>
</WixDesignSystemProvider>
);
}
Note: When using dynamic parameters, use the withProviders wrapper instead. See Dynamic Parameters for details.
Modal component or custom React modal implementations - Always use dashboard modals (see wix-cli-dashboard-modal) for any popup dialogs, forms, or overlaysRequest: "Create a dashboard page to manage blog posts"
Output: Page with table displaying posts, search toolbar, add/edit/delete actions, empty state.
Request: "Build a settings page for notification preferences"
Output: Page with form fields, save button with toast confirmation, unsaved changes warning.
Request: "Create an admin panel for customer orders"
Output: Page with orders table, status badges, filters, detail dashboard modal (using wix-cli-dashboard-modal), status update actions.
Request: "Create a settings page for the coupon popup embedded script"
Output: Page with form fields for popup headline, coupon code, minimum cart value, and enable toggle. Uses embeddedScripts API to load/save parameters.
// Key pattern for embedded script configuration pages
import { embeddedScripts } from "@wix/app-management";
// Load on mount
useEffect(() => {
const load = async () => {
const script = await embeddedScripts.getEmbeddedScript();
const data = script.parameters || {};
setOptions({
headline: data.headline || "Default",
enabled: data.enabled === "true",
threshold: Number(data.threshold) || 0,
});
};
load();
}, []);
// Save handler
const handleSave = async () => {
await embeddedScripts.embedScript({
parameters: {
headline: options.headline,
enabled: String(options.enabled),
threshold: String(options.threshold),
},
});
dashboard.showToast({ message: "Saved!", type: "success" });
};
Extension registration is MANDATORY and has TWO required steps.
Each dashboard page requires an extensions.ts file in its folder:
File: src/extensions/dashboard/pages/<page-name>/extensions.ts
import { extensions } from "@wix/astro/builders";
export const dashboardpageMyPage = extensions.dashboardPage({
id: "{{GENERATE_UUID}}",
title: "My Page",
routePath: "my-page",
component: "./extensions/dashboard/pages/my-page/page.tsx",
});
CRITICAL: UUID Generation
The id must be a unique, static UUID v4 string. Generate a fresh UUID for each extension - do NOT use randomUUID() or copy UUIDs from examples. Replace {{GENERATE_UUID}} with a freshly generated UUID like "a1b2c3d4-e5f6-7890-abcd-ef1234567890".
| Property | Type | Description |
|---|---|---|
id | string | Unique static UUID v4 (generate fresh - see note above) |
title | string | Display title in dashboard sidebar |
routePath | string | URL path segment. Lowercase letters, numbers, dashes, and slashes only. Must NOT start with a slash. |
component | string | Relative path to the page component (.tsx) |
CRITICAL: After creating the page-specific extension file, you MUST read wix-cli-extension-registration and follow the "App Registration" section to update src/extensions.ts.
Without completing Step 2, the dashboard page will not appear in the Wix dashboard.
API confusion with other extension types:
| WRONG (Embedded Script API) | CORRECT (Dashboard Page API) |
|---|---|
name: "..." | title: "..." |
source: "..." | component: "..." |
route: "..." | routePath: "..." |
Do NOT copy field names from embedded script or other extension registrations. Dashboard pages use title, routePath, and component.
Token limits: Your max output is ~10,000 tokens. You MUST plan your response to stay well under this limit.
Brevity rules: Minimize output tokens while maintaining quality and correctness.
Modular code strategy: When generating substantial code, split into multiple smaller files with imports:
When an API specification is provided, you can make API calls to those endpoints. See API Spec Reference for details on how to use API specs in dashboard pages.
Layout determines how users interact with your dashboard content. It establishes the structure, hierarchy, and rhythm of your dashboard page, contributing to the overall coherence and user experience. By making mindful and calculated choices in how you organize your content, users can move around more smoothly, saving time and frustration when completing tasks.
To create dashboard pages optimized for user experience, follow these design principles:
Dashboard pages are designed to accommodate various screen sizes rather than being tailored to one specific resolution. The primary content should be at the top of the page to ensure users immediately understand the purpose of the page.
Note: Content displayed in the top 600 pixels of the page will be visible for the majority of users.
The base unit establishes the increment by which all elements and measurements are multiplied. This practice ensures consistency in the spacing and sizing of design elements.
Note: The design system is based on a 6px unit.
The layout grid, spacing tokens, and nearly all visual elements and sizes adhere to multiples of six (6, 12, 18, 24, etc.), with only occasional exceptions.
| TOKEN | SIZE | USE FOR |
|---|---|---|
| SP1 | 6px | Spacing between components |
| SP2 | 12px | Spacing between components |
| SP3 | 18px | Spacing between components |
| SP4 | 24px | Spacing between components, layout spacing |
| SP5 | 30px | Layout spacing |
| SP6 | 36px | Layout spacing |
| SP7 | 42px | Layout spacing |
| SP8 | 48px | Layout spacing |
| SP10 | 54px | Layout spacing |
| SP11 | 60px | Layout spacing |
To best design the layout for your app, understand:
The dashboard app frame is used by the majority of Wix applications settings. Dashboard pages consist of 4 areas:
| AREA | USAGE |
|---|---|
| 1. Global navigation (top bar) | General navigation at the top of a page which allows users to navigate between different environments. Full width container with a fixed height of 48px. |
| 2. Sidebar navigation | Local navigation of an environment. Container with a fixed width of 228px. |
| 3. Content area | Page content area with a width that's adaptive to screen size. |
| 4. Side panel (optional) | An optional panel that shows additional actions or content associated with the content of a page. Fixed width of 420px. Can either overlay the main content area or push it from the right side. |
Side Panel Guidelines:
The system uses a fluid grid layout with a fixed maximum width. It uses columns that scale and resize the content accordingly.
The grid is constructed from 3 elements:
Grid Specifications:
Page layouts can be divided by intention into the following types:
Forms are pages that allow users to fill in data or edit existing data. Two variations:
Both form page layouts include mandatory Save and Cancel actions in the header and footer areas.
2/3 Layout Best Practices:
Full Width Layout Best Practices:
Combining Layouts:
Note: A column is easy to read if it is wide enough to accommodate an average of 10 words per line.
Display pages showcase data or content without accepting input from users. They can contain minor actions such as data filtering.
List (Table):
List (Grid) Options:
Grid Selection Considerations:
Dashboards: Display different types of data on a specific topic using a combination grid.
Column span recommendations:
Empty States:
Marketing pages promote new products that site owners are not aware of yet. Built using the <MarketingPageLayout/> component split into 2 columns:
Optional footer area can display features or testimonials list.
Wizard pages guide users through setting up a product or feature. They split complex forms into steps for easier completion.
Entry Points:
Note: Wizards must have a final destination. After completing all steps, users should end up on a relevant page: a dashboard, a details page, or any other relevant location.
<Page /> - Main page wrapper<Layout /> - Grid layout container<MarketingPageLayout /> - Marketing page wrapper<Card /> - Content container with 24px gaps between cards