Add a Site Widget Extension with the Wix CLI

The Wix CLI makes it easy to add and develop custom element site widgets in your app project. These are considered app extensions, and appear on the Extensions page in your app's dashboard. For more general information about site widgets, read About Site Widget Extensions

Custom element site widgets extensions are built in the CLI with custom element technology. The custom element is essentially a new HTML tag that you define, which is made available in the Wix editors as a widget.

The Wix CLI creates the necessary files with template code so you can easily start developing your site widget. It also calls define() for the custom element that the site widget is built on, so you don't need to explicitly call it in your code.

Follow the instructions below to:

1. Add a custom element site widget to your app project.
2. Test the site widget on a site.
3. Deploy your app with the site widget.

Step 1 | Add a site widget to your app project

In the terminal:

1. Navigate to your project repo.

2. Run the generate command.

   The CLI will display a menu of extensions to generate. Select Site Widget and hit enter. The CLI will then prompt you for the following items:

   • Element name: The name of the element that appears in the element.json configuration file. Only you will see this.
   • Element folder: The name of the folder in the project repo that contains the custom element code that the site widget is built on. Only you will see this.

Upon completion, the extension files will be created in your project directory with the following structure:

Learn more about the site widget extension files.

Step 2 | Testing your site widget

You can test your site widget while you're developing by running the dev command. Select the option in the CLI menu to view your site widget in the editor. This will open your test site editor, where you can view and try out your site widget.

Why do I get a placeholder when previewing my site widget?

In some cases, your site widget doesn't display when previewed, but does display as expected when viewed on a published site. We are currently working to fix this issue, but in the meantime, we display a placeholder.

This can happen if:

• You open the dashboard, site, or editor from the menu options. Run the dev command to restart your local environment.
• You preview a site when the site was opened with the editor menu option. Run the build command and then the release command to release a new version.

Step 3 | Build and deploy your project

Once your app project is ready for production, you can build it and release a version in the app dashboard.

1. Run the build command.

2. Run the release command and follow the prompts to release an app version.

An app version allows you to publish an app to the Wix App Market or install it on a site with a direct install URL. You can view your app versions in the app dashboard.

For more information about building and deploying your app, see Build and Deploy an App with the Wix CLI.

Delete a site widget extension

To delete an existing site widget extension from your app:

1. Delete the folder that contains your site widget's files.
2. Remove the import and .use() statements for the extension from the extensions.ts file.