Site Widget Extension Files and Code
Add a new site widget to your CLI project with the following command:
1
The CLI generates this directory structure in your project repo:
1
In the your site widget folder, three files are created:
- An
element.jsonfile that defines the site configuration settings of your site widget. - An
element.tsxfile that contains the main code for the custom element that the site widget is built on. - An
panel.tsxfile that contains the code for your file.
It is possible to create each of these files yourself, but we don't recommend it for a couple of reasons:
- You're more likely to make errors in the filepath if you add the files and folders yourself. If the filepath is incorrect, the CLI can't detect the custom element and the site widget won't work.
- The auto-generated files offer React template code that helps you get started developing.
element.json
The element.json file configures the settings for how your site widget appears a user's site. This file is required, so don't delete it after the site widget is generated. If you add your own files, you must include element.json.
When you generate a new site widget in your project, you'll see the following code in element.json:
1
You can edit the JSON and add to the keys defined here. Here is an example of a full element.json file that uses all the available keys:
1
| Field | Type | Description |
|---|---|---|
id | string | A unique identifier for your site widget. The CLI generates this GUID for you. If you add the JSON file yourself, you must generate your own GUID. |
name | string | The name of the site widget as it appears in the Wix Dev Center. The CLI prompts you for the name when you create the site widget. |
height.defaultHeight | number | Sets the widget's height in pixels when it is first installed on a site. |
width.defaultWidth | number | Sets the widget's width in pixels when it is first installed on a site. |
width.stretchByDefault | boolean | Sets the widget's stretch on installation. If set to true, it will stretch the widget to the full width of its container. |
width.allowStretch | boolean | Allows a user to stretch the widget to the full width of the container if true. |
installation.autoAddToSite | boolean | Automatically adds the widget to a site upon installation if true. |
installation.essential | boolean | Marks the widget as crucial to your app's functionality or not. If true and a user deletes the widget, the entire app will also be deleted. |
installation.maxInstances | boolean | Defines whether users can create multiple instances of your widget on their site by duplicating it in the editor. |
element.tsx
The element.tsx file is where you write the code for the custom element that defines the site widget. 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 widget definition.
This file is required for the site widget to work, so don't delete it. If you add the files on your own, you must include element.tsx.
When the element.tsx file is generated, it looks like this:
1
The file sets up a React component called 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 site widget.
We recommend writing your code in React, since the rest of the CLI also works with React. However, you can also write code directly in element.tsx with Javascript. If you do so, make sure to export the custom element, like in the example below:
1
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.
panel.tsx
The panel.tsx file contains the code defining your site widget's settings panel. The settings panel lets site users customize the widget after they install your app. You're not required to include the panel.tsx file. However, without this file, your site widget won't have a settings panel.
After the site widget is generated, you'll see code like this in panel.tsx file:
1
The file contains two important pieces of code:
- A React component called
SettingsPanelwhere you write your code defining the site widget's settings panel. - A function
withProviders()that wraps the component with the necessary React providers. This includes the<WixDesignSystemProvider>and<WixProvider>.
As with element.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.