Wix Site Plugin Builder

Creates site plugin extensions for Wix CLI applications. Site plugins are custom elements that integrate into predefined slots within Wix business solutions (like Wix Stores, Wix Bookings), extending their functionality and user experience.

Site owners can place site plugins into UI slots using the plugin explorer in Wix editors.

Quick Start Checklist

Follow these steps in order when creating a site plugin:

Create plugin folder:

src/extensions/site/plugins/<plugin-name>/

Create

<plugin>.tsx

extending

HTMLElement

with

observedAttributes

Create

<plugin>.panel.tsx

with WDS components and

widget.getProp/setProp

Create

<plugin>.extension.ts

with

extensions.sitePlugin()

and unique UUID

Update
```
src/extensions.ts
```
to import and use the new extension
Run
```
npx tsc --noEmit
```
to verify TypeScript compiles
Run
```
npx wix build
```
and
```
npx wix preview
```
to test
Verify plugin appears in plugin explorer for target slots

Architecture

Site plugins consist of three required files:

1. Plugin Component (

<plugin-name>.tsx

)

Custom element component that renders in the slot using native HTMLElement:

Extend
```
HTMLElement
```
class
Define
```
observedAttributes
```
for reactive properties

Implement

connectedCallback()

and

attributeChangedCallback()

for rendering

Use inline styles via template strings
Attributes use kebab-case (e.g.,
```
display-name
```
)

2. Settings Panel (

<plugin-name>.panel.tsx

)

Settings panel shown in the Wix Editor sidebar:

Uses Wix Design System components (see WDS-COMPONENTS.md)
Manages plugin properties via
```
@wix/editor
```
widget API
Loads initial values with
```
widget.getProp('kebab-case-name')
```

Updates properties with

widget.setProp('kebab-case-name', value)

Wrapped in

WixDesignSystemProvider > SidePanel > SidePanel.Content

3. Extension Configuration (

<plugin-name>.extension.ts

)

Defines the plugin's placement configuration:

Specifies which slots the plugin can be added to
Configures auto-add behavior on app installation
Sets the tag name and file paths

Plugin Component Pattern

Site plugins use native

HTMLElement

custom elements:

typescript

// my-site-plugin.tsx
class MyElement extends HTMLElement {
  static get observedAttributes() {
    return ['display-name'];
  }

  constructor() {
    super();
  }

  connectedCallback() {
    this.render();
  }

  attributeChangedCallback() {
    this.render();
  }

  render() {
    const displayName = this.getAttribute('display-name') || "Your Plugin's Title";

    this.innerHTML = `
      <div style="font-size: 16px; padding: 16px; border: 1px solid #ccc; border-radius: 8px; margin: 16px;">
        <h2>${displayName}</h2>
        <hr />
        <p>
          This is a Site Plugin generated by Wix CLI.<br />
          Edit your element's code to change this text.
        </p>
      </div>
    `;
  }
}

export default MyElement;

Key Points:

Extend
```
HTMLElement
```
class directly
Define
```
observedAttributes
```
static getter to list reactive attributes
Attributes use kebab-case (e.g.,
```
display-name
```
,
```
bg-color
```
)
Implement
```
connectedCallback()
```
for initial render
Implement
```
attributeChangedCallback()
```
to re-render when attributes change
Use inline styles via template strings
Use
```
this.getAttribute('attribute-name')
```
to read attribute values

Settings Panel Pattern

typescript

// my-site-plugin.panel.tsx
import React, { type FC, useState, useEffect, useCallback } from 'react';
import { widget } from '@wix/editor';
import {
  SidePanel,
  WixDesignSystemProvider,
  Input,
  FormField,
} from '@wix/design-system';
import '@wix/design-system/styles.global.css';

const Panel: FC = () => {
  const [displayName, setDisplayName] = useState<string>('');

  useEffect(() => {
    widget.getProp('display-name')
      .then(displayName => setDisplayName(displayName || "Your Plugin's Title"))
      .catch(error => console.error('Failed to fetch display-name:', error));
  }, [setDisplayName]);

  const handleDisplayNameChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
    const newDisplayName = event.target.value;
    setDisplayName(newDisplayName);
    widget.setProp('display-name', newDisplayName);
  }, [setDisplayName]);

  return (
    <WixDesignSystemProvider>
      <SidePanel width="300" height="100vh">
        <SidePanel.Content noPadding stretchVertically>
          <SidePanel.Field>
            <FormField label="Display Name">
              <Input
                type="text"
                value={displayName}
                onChange={handleDisplayNameChange}
                aria-label="Display Name"
              />
            </FormField>
          </SidePanel.Field>
        </SidePanel.Content>
      </SidePanel>
    </WixDesignSystemProvider>
  );
};

export default Panel;

Key Points:

Prop names in

widget.getProp()

and

widget.setProp()

use kebab-case (e.g.,

"display-name"

)

Always update both local state AND widget prop in onChange handlers

Wrap content in

WixDesignSystemProvider > SidePanel > SidePanel.Content

Use WDS components from
```
@wix/design-system
```
Import
```
@wix/design-system/styles.global.css
```
for styles
Include
```
aria-label
```
for accessibility

Attribute Naming Convention

Site plugins use kebab-case consistently for HTML attributes:

File	Convention	Example
`<plugin>.tsx` (getAttribute)	kebab-case	`this.getAttribute('display-name')`
`<plugin>.tsx` (observedAttributes)	kebab-case	`['display-name', 'bg-color']`
`<plugin>.panel.tsx` (widget API)	kebab-case	`widget.getProp('display-name')`

Output Structure

Site plugins live under

src/extensions/site/plugins

. Each plugin has its own folder with files named after the plugin.

src/extensions/site/plugins/
└── {plugin-name}/
    ├── {plugin-name}.tsx           # Main plugin component (HTMLElement)
    ├── {plugin-name}.panel.tsx     # Settings panel component
    └── {plugin-name}.extension.ts  # Extension registration
public/
└── {plugin-name}-logo.svg          # Plugin logo (optional)

References

Topic	Reference
Complete Examples	EXAMPLES.md
Slots (App IDs, multiple placements, finding slots)	SLOTS.md
WDS Components	WDS-COMPONENTS.md

Available Slots

Site plugins integrate into predefined slots in Wix business solutions. Each slot is identified by:

appDefinitionId: The ID of the Wix app (e.g., Stores, Bookings)
widgetId: The ID of the page containing the slot
slotId: The specific slot identifier

Common placement areas include product pages (Wix Stores), booking pages (Wix Bookings), service pages, and event pages.

For supported pages, common Wix App IDs, and how to find slot IDs, see SLOTS.md.

Extension Registration

Extension registration is MANDATORY and has TWO required steps.

Step 1: Create Plugin-Specific Extension File

Each site plugin requires an extension file in its folder:

typescript

// my-site-plugin.extension.ts
import { extensions } from '@wix/astro/builders';

export default extensions.sitePlugin({
  id: '{{GENERATE_UUID}}',
  name: 'My Site Plugin',
  marketData: {
    name: 'My Site Plugin',
    description: 'Marketing Description',
    logoUrl: '{{BASE_URL}}/my-site-plugin-logo.svg',
  },
  placements: [{
    appDefinitionId: 'a0c68605-c2e7-4c8d-9ea1-767f9770e087',
    widgetId: '6a25b678-53ec-4b37-a190-65fcd1ca1a63',
    slotId: 'product-page-details-6',
  }],
  installation: { autoAdd: true },
  tagName: 'my-site-plugin',
  element: './extensions/site/plugins/my-site-plugin/my-site-plugin.tsx',
  settings: './extensions/site/plugins/my-site-plugin/my-site-plugin.panel.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

"95a28afd-7df1-4e09-9ec1-ce710b0389a0"

Property	Type	Description
`id`	string	Unique static UUID v4 (generate fresh)
`name`	string	Internal name for the plugin
`marketData.name`	string	Display name in plugin explorer and app dashboard
`marketData.description`	string	Description shown in plugin explorer and app dashboard
`marketData.logoUrl`	string	Path to logo file ( `{{BASE_URL}}` resolves to public folder)
`placements`	array	Array of slot placements where plugin can be added
`placements.appDefinitionId`	string	ID of the Wix app containing the slot
`placements.widgetId`	string	ID of the page containing the slot
`placements.slotId`	string	ID of the specific slot
`installation.autoAdd`	boolean	Whether to auto-add plugin to slots on app installation
`tagName`	string	HTML custom element tag (kebab-case, must contain a hyphen)
`element`	string	Relative path to plugin component
`settings`	string	Relative path to settings panel component

Step 2: Register in Main Extensions File

CRITICAL: After creating the plugin-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 site plugin will not be available in the plugin explorer.

Examples

For complete examples with all three required files (plugin component, settings panel, extension configuration), see EXAMPLES.md.

Example use cases:

Best Seller Badge - Customizable badge on product pages with text and color settings
Booking Confirmation - Custom confirmation message for booking pages
Product Reviews Summary - Star rating and review count display
Data-Driven Plugin - Plugin with Wix Data API integration and editor environment handling

Best Practices

Implementation Guidelines

Use inline styles - CSS imports are not supported in custom elements
Handle editor environment - Show placeholders when in editor mode for data-dependent plugins
Editor sandboxing - Plugins are sandboxed in the Editor;
```
localStorage
```
,
```
sessionStorage
```
, and cookies are restricted. Use
```
viewMode()
```
to detect editor and mock storage if needed
Validate all input - Check required props are present
Follow naming conventions - kebab-case for all attributes and widget API
Keep plugins focused - Each plugin should do one thing well
Test in multiple slots - If supporting multiple placements, test each one

Performance Considerations

Keep bundle size small - plugins load on user-facing pages
Avoid heavy computations on initial render
Lazy load data when possible
Use efficient re-rendering patterns

Verification

After implementation, use wix-cli-app-validation to validate TypeScript compilation, build, preview, and runtime behavior.

Code Quality Requirements

Strict TypeScript (no
```
any
```
, explicit return types)
Native HTMLElement class for plugin components
React functional components with hooks for settings panels
Proper error handling and loading states
No
```
@ts-ignore
```
comments
Inline styles via template strings (no CSS imports)
Handle Wix Editor environment when using Wix Data API
Consistent attribute naming using kebab-case throughout

wix-cli-site-plugin

NPX Install

Tags

SKILL.md Content

Wix Site Plugin Builder

Quick Start Checklist

Architecture

1. Plugin Component (
`<plugin-name>.tsx`
)

2. Settings Panel (
`<plugin-name>.panel.tsx`
)

3. Extension Configuration (
`<plugin-name>.extension.ts`
)

Plugin Component Pattern

Settings Panel Pattern

Attribute Naming Convention

Output Structure

References

Available Slots

Extension Registration

Step 1: Create Plugin-Specific Extension File

Step 2: Register in Main Extensions File

Examples

Best Practices

Implementation Guidelines

Performance Considerations

Verification

Code Quality Requirements

wix-cli-site-plugin

NPX Install

Tags

SKILL.md Content

Wix Site Plugin Builder

Quick Start Checklist

Architecture

1. Plugin Component (<plugin-name>.tsx)

2. Settings Panel (<plugin-name>.panel.tsx)

3. Extension Configuration (<plugin-name>.extension.ts)

Plugin Component Pattern

Settings Panel Pattern

Attribute Naming Convention

Output Structure

References

Available Slots

Extension Registration

Step 1: Create Plugin-Specific Extension File

Step 2: Register in Main Extensions File

Examples

Best Practices

Implementation Guidelines

Performance Considerations

Verification

Code Quality Requirements

1. Plugin Component (
`<plugin-name>.tsx`
)

2. Settings Panel (
`<plugin-name>.panel.tsx`
)

3. Extension Configuration (
`<plugin-name>.extension.ts`
)