Add a Blocks Site Widget Extension in the CLI

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.

Blocks site widget extensions are site widget extensions created with a hybrid development workflow that combines the visual design capabilities of Wix Blocks with the CLI development environment. Learn more about the Blocks-CLI integration.

This extension 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.

Note: Site widgets can be developed entirely in the CLI using the Custom element site widget extension.

Follow the instructions below to:

  • Add a site widget to your app.
  • Test the site widget on a site.
  • Deploy your app with the site widget.

Before you begin

Step 1 | Add a site widget to your app

In the terminal:

  1. Navigate to your project repo.

  2. Run the following command:

    Copy

    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, it 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.

  3. Run npm run dev, then press ’B’. The Blocks Editor will open in a new tab.

  4. Design the UI for your widget in Blocks, then click Sync to sync your design to your local code files.

Note: You only need to run the generate command the first time you create a widget in your project. To create a new widget, open the Blocks Editor again, add a new widget, and click Sync.

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

Copy
  • api.ts - This file contains the declarations for your Widget API properties, events, and functions. These are exposed when your widget is installed on a site (in the Wix Editors) or when it's added inside another widget.
  • widget.json - This file contains the ID of your widget. Do not modify this file.
  • widget.ts - This file contains the logic for your widget. Here you implement and use the properties, events, and functions that you declared in api.ts.

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. These subdirectories each contain the following files:

  • panel.json - this file contains the ID of your panel. Do not modify this file.
  • panel.ts - This file contains the logic for your panel.

For example:

Copy

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.

Step 2 | Develop and test your site widget

Your widget's UI is managed in Blocks, and its code is managed in the CLI.

To develop your widget's UI:

  1. Run npm run dev, then press ’B’ to open the Blocks Editor.
  2. Design the UI for your widget in Blocks, then click Sync to sync your design to your local code files.

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:

Copy

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 can only be tested in the editor, for example, use of the Editor API.

  • 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 can only be tested on a live site, for example, use of the Site API.

    Before you can test your site widget on your test site, you must complete the following one-time setup:

    1. Build and release your app.
    2. Add your widget to your test site in the editor and publish the site.

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.

Step 3 | Build and deploy your app

Once your app is ready for production, you can build it and release an app version.

  1. Run the following command to build your app:

    Copy

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

    Copy

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.

See also

Did this help?