Add a new site plugin to your CLI project with the following command:
The CLI generates this directory structure in your project repo:
The following files are created in your site plugin's folder:
panel.tsx file that contains the code for the site plugin's settings panel.plugin.json file that configures how your site plugin integrates with a Wix site. It defines the locations where the plugin can be added.plugin.module.css file that configures CSS styling to customize your plugin's appearance. It is generated with some initial styles to help you get started.plugin.tsx contains the custom element code that supports the site plugin.It is possible to create a site plugin extension manually by adding these files yourself, but we don't recommend it for a couple of reasons:
A site-plugin-logo.png file is also created in your app's /public folder. This is used as your plugin's logo in the plugin explorer in the editor. This file is not required, however it is referenced in the logoUrl field in the plugin.json file. If you rename this file, you must update the path in logoUrl. If you remove the file, you must remove the logoUrl property entirely.
The plugin.json file configures which slots your plugin can be added to. This file is required, so don't delete it after the site plugin is generated. If you add your own files, you must include a plugin.json.
When you generate a new site plugin in your project, you'll see the following code in plugin.json (placements will contain the details your selected plugin slot):
The placements array is generated with the details of the slot you selected. You can add slots to the placements array to allow your plugin to be added to multiple slots. For detailed information on each available slot, see About Slots.
By default, your file is configured so that your app will add the plugin to its slots on the site automatically upon installation.
If you have more than one placement for slots on a single page, the plugin will be added to the first slot in the array by default. Users may then manually move the plugin to their desired location in the editor.
| Field | Type | Description |
|---|---|---|
$schema | string | The URL of the schema file that provides autocomplete information for this file. |
id | string | A unique identifier for your site plugin. The CLI generates this GUID for you. If you add the JSON file yourself, you must generate your own GUID. |
referenceComponentId | string | A unique identifier for your plugin's custom element . The CLI generates this GUID for you. If you add the JSON file yourself, you must generate your own GUID. |
marketData.name | string | The name of your plugin as it will appear in the plugin explorer in the editor and in your app dashboard. |
marketData.logoUrl | string | The URL of your app's logo file. {{PUBLIC_URL}} automatically resolves to the location of your /public folder, so the full string including the filename will link to your logo at the production URL or your local development server URL if you are testing your app locally. |
placements | array | An array of placement objects that define the slots your plugin can be added to. For detailed information on each available slot, see About Slots. |
placements.appDefinitionId | string | The ID of the app the slot belongs to. |
placements.widgetId | string | The ID of the page containing the slot. |
placements.slotId | string | The ID of the slot your plugin can be added to. |
installation.autoAddToSite | boolean | Whether the plugin should be added to the specified slots automatically when your app is installed on a site. |
The plugin.tsx file is where you write the code for the custom element that defines the site plugin. You can write code in other files and include it here, but you must return your main component in this file. This is where the CLI will look for the site plugin definition.
This file is required for the site plugin to work, so don't delete it. If you add the files on your own, you must include plugin.tsx.
When the plugin.tsx file is generated, it looks like this:
The file sets up a React component named CustomElement where you write the custom element code. It also calls reactToWebComponent to convert your React component to a custom element, and exports the custom element so Wix can work with it as a widget.
When using reactToWebComponent, attribute updates are automatically reflected in your plugin in the editor. To manually handle attribute updates so they are reflected in your widget in the editor, use attributeChangedCallback() in your custom element's code.
Note that you don't need to call define() even here; Wix still takes care of that for you even if you haven't defined the custom element in React.
Each slot supports an API that provides data about the plugin's context (for example the productId of the current product on the Product page). This data is available to your site plugin in the props passed to your custom element.
These properties are listed in the documentation for each slot.
In your code, you first need to define the prop. This is done in the same way the name prop is defined in plugin.tsx. For example:
You can then access the prop's data in your custom element code in the same way we do for name. For example:
To get updates from the custom element, you need to register for them in the same way we do for name. For example:
The panel.tsx file contains the code defining your site plugin's settings panel. The settings panel lets site users customize the plugin after they install your app. You're not required to include the panel.tsx file. However, without this file your site plugin won't have a settings panel.
When the plugin.tsx file is generated, it looks like this:
The file contains a React component called Panel where you write your code defining the plugins's settings panel.
WixDesignSystemProvider wraps the child components to align them with Wix's design conventions.
The file also contains a useEffect hook to fetch and set the initial value of the name property from the plugin's properties when the component mounts.
As with plugin.tsx, you can write code in other files and include it here, but you must return your main component in this file. The panel code must be written in React to work with the rest of the CLI.
You can manage the properties of your site plugin's custom element using the Widget API. You can also use Wix's JavaScript SDK in the panel’s code to retrieve environmental data from the editor and access and manage Wix business solutions.
To apply changes made in the settings panel to the plugin, use the Widget API’s setProp() function. Widget properties are bound to your custom element’s attributes, so any change in the properties automatically updates the corresponding attribute.