This feature is in Developer Preview and is subject to change.
The Wix CLI makes it easy to add and develop site widgets in your app. These are considered app extensions, and appear on the Extensions page in your app's dashboard.
The CLI offers two types of site widget extensions: Blocks site widget extensions and custom element site widget extensions. Read more about the differences between the types and the benefits of each in About Site Extensions.
Blocks site widget extensions are created with a hybrid development workflow that combines the visual design capabilities of Wix Blocks with the CLI development environment.
This allows you to design your widget in the Wix Blocks Editor, and then sync it to the CLI where you can develop its code locally.
When your widget is synced from Blocks, the CLI adds the necessary files with template code so you can easily start developing.
Learn more about the Blocks-CLI integration.
Note: Unlike other CLI extensions, Blocks site widget extensions can’t be created by manually adding the required code files to your app. You must create a widget in Blocks, then sync it to the CLI.
Follow the instructions below to:
In the terminal:
Navigate to your project repo.
Run the following command:
The CLI displays a menu of extensions to generate. Select Site Widget and press enter, then select Blocks and press enter.
The first time you run this command, the CLI configures your project's integration with Blocks behind the scenes and creates a widget in Blocks. It then displays instructions on how to finish setting up the extension.
Note: You only need to run the generate command the first time you create a widget in your project.
Run npm run dev, then press ’B’. The Blocks Editor opens in a new tab.
Design the UI for your widget in Blocks, then click Sync in Blocks to sync your design to your local code files.
To create a new widget, open the Blocks Editor again, add a new widget, and click Sync.
Upon completion, the extension's files are added to your project’s directory with the following structure:
For more information, see Files and Code for Blocks Site Widgets.
If you add panels to your widget in the Blocks editor, a panels directory is created inside your widget’s directory. panels contains subdirectories for each panel you added in Blocks.
For example:
For more information, see Files and Code for Blocks Site Widget Panels.
Your widget's UI is managed in Blocks, and its code is managed in the CLI.
To develop your widget's UI:
npm run dev, then press ’B’ to open the Blocks Editor.To develop your widget's code, edit your widget extension's files in the CLI.
You can test your site widget while you're developing by running the following command:
You can then either:
Press E to view your site widget in the editor. This opens your test site editor in your browser, where you can view and try out your site widget and custom panels as they will appear to Wix users. Certain behavior, such as using the Editor API, can only be tested in the editor.
Press S to view your site widget on your test site. This opens the live site in your browser where you can try out your site widget and custom panels as they appear to site visitors and members. Certain behavior, such as using the Site API, can only be tested on a live site.
Before you can test your site widget on your test site, you must complete the following one-time setup:
When you sync changes from the Blocks Editor or make changes to your extension's code in the CLI, the changes are immediately reflected in the test site and editor.
Once your app is ready for production, you can build it and release an app version.
Run the following command to build your app:
Run the following 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. 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 CLI.
To delete a Blocks site widget extension from your app, delete the widget in the Blocks editor and sync the changes to the CLI. Deleting the widget's files in your IDE won't delete the widget in Blocks, and the files will be restored to your project the next time you sync from Blocks.
Note: If you've already created a version of your app, deleting a Blocks site widget from your project does not remove it from your app's latest version in the app dashboard. To remove it from the app dashboard, create a new version after deleting the extension in your project.