The Wix CLI is in Developer Preview and is subject to change.
CLI Documentation Notice
You're viewing documentation for the new Wix CLI, which we recommend for all new projects. Determine which CLI your project uses.
Previous CLI documentation:
Add a new site plugin to your CLI project with the generate command.
The CLI generates this directory structure in your project repo:
The following files are created in your site plugin's folder:
your-plugin-name.panel.tsx file that contains the code for the site plugin's settings panel.your-plugin-name.extension.ts file that configures how your site plugin integrates with a Wix site. It defines the locations where the plugin can be added.your-plugin-name.tsx file contains the custom element code that supports the site plugin.A your-plugin-name-logo.svg file is also created inside the public folder.
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 logo.svg file is created inside the public folder when you generate this extension. The file is used as your plugin's logo in the plugin explorer in the editor. The file isn't required, however, it's referenced in the logoUrl field in the your-plugin-name.extension.ts file.
Important:
If you rename the file, you must update the path in logoUrl. If you remove the file, you must remove the logoUrl property entirely. The file must be a square JPG, PNG, or SVG.
The your-plugin-name.extension.ts 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 your-plugin-name.extension.ts.
When you generate a new site plugin in your project, you'll see the following code in your-plugin-name.extension.ts (placements will contain the details of 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 |
|---|---|---|
id | string | A unique identifier for your site plugin. The CLI generates this GUID for you. If you add the extension file yourself, you must generate your own GUID. |
name | string | Your name for the plugin. |
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.description | string | The description of your plugin as it will appear in the plugin explorer in the editor and in your app dashboard. |
marketData.logoUrl | string | The relative path from your your-plugin-name.extension.ts to your logo file. |
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 that the slot belongs to. |
placements.widgetId | string | The ID of the page that contains 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. |
tagName | string | The custom HTML element tag name for your site plugin (for example, bookings-plugin). This tag name is used to render your plugin as a custom element in the site, similar to standard HTML tags like <div> or <h1>. Must follow custom element naming rules (lowercase, contain a hyphen). |
element | string | The relative path from your your-plugin-name.extension.ts to your custom element file. |
settings | string | The relative path from your your-plugin-name.extension.ts to your site plugin's settings file. |
The your-plugin-name.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 looks 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 your-plugin-name.tsx.
When the your-plugin-name.tsx file is generated, it looks like this:
The file sets up a web component named MyElement where you write the custom element code.
In this example, displayName is fetched from the your-plugin-name.panel.tsx and shown in the UI.
The your-plugin-name.panel.tsx file contains the code that defines your site plugin's settings panel. The settings panel lets site users customize the plugin after they install your app.
When the your-plugin-name.panel.tsx file is generated, it looks like this:
The file contains a React component called Panel where you write the code that defines the plugin'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 displayName property from the plugin's properties when the component mounts.
As with your-plugin-name.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 project.
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.
Learn more about creating a settings panel for a site plugin built with the CLI.