> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Add a Site Widget Extension in the CLI

## Article: Add a Site Widget Extension in the CLI

## Article Link: https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/site-extensions/custom-element-site-widgets/add-a-site-widget-extension-in-the-cli.md

## Article Content:

# Add a Custom Element Site Widget Extension with the Wix CLI for Apps

<blockquote classname="warning">

**Deprecated**

The Wix CLI for Apps is deprecated and no longer receives updates or new features. New projects should use the unified [Wix CLI](https://dev.wix.com/docs/wix-cli/guides/about-the-wix-cli.md). [Determine which CLI your project uses](https://dev.wix.com/docs/wix-cli/guides/development/determine-which-cli-your-project-uses.md).

</blockquote>


The Wix CLI makes it easy to add and develop [site widgets](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/site-extensions/site-widgets/about-site-widget-extensions.md) 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](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/site-extensions/about-site-extensions.md#site-widget-extensions).

Custom element site widgets extensions are site widget extensions built in the CLI with [custom element](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements) 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()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/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.
1. Test the site widget on a site.
1. Deploy your app with the site widget.

## Before you begin

+ You must have an app project that was [created using the Wix CLI](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/get-started/quick-start.md).
+ You must be logged into your Wix Studio account. If you don't already have one, [sign up for a Wix Studio account](https://manage.wix.com/account/custom-apps).

## Step 1 | Add a site widget to your app

In the terminal:

1. Navigate to your project repo.
1. Run the following command:

    ```tsx
    npm run generate
    ```

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

    + **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.
    + **Element name**: The name of the element that appears in the `element.json` configuration file. Only you will see this.

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

```tsx
.
└── <your-app-name>/
    └── src/
        ├── assets/
        │   └── <your-widget-name>/
        │       └── thumbnail.png
        └── site/
            └── widgets/
                └── custom-elements/
                    └── <your-widget-name>/
                        ├── element.json
                        ├── element.tsx
                        └── panel.tsx
```

+ [`thumbnail.png`](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/site-extensions/custom-element-site-widgets/site-widget-extension-files-and-code.md) - This file is optional and is the thumbnail displayed in the *Add Panel* for your site widget. Without a thumbnail, your widget will not appear in the Add Panel.
+ [`element.json`](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/site-extensions/custom-element-site-widgets/site-widget-extension-files-and-code.md) - This file is required and configures how your site widget integrates with a Wix site. For example, it sets the widget's width and height on the site. It is generated with default settings that can be edited later.
+ [`element.tsx`](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/site-extensions/custom-element-site-widgets/site-widget-extension-files-and-code.md) - This file is required and contains the custom element code that supports the site widget.
+ [`panel.tsx`](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/site-extensions/custom-element-site-widgets/site-widget-extension-files-and-code.md) - This file is required and contains the code for the site widget settings panel.

## Step 2 | Testing your site widget

You can test your site widget while you're developing by running the following command:

```bash
npm run dev
```

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.

<details>  

<summary>Why do I get a placeholder when previewing my site widget?  
<br/>
<img src="https://wixmp-833713b177cebf373f611808.wixmp.com/images/8702911980d16e72feb39e180d7d0f51.jpg" style="max-width: 8vw" />
<br/>
</summary>

In some cases, your site widget does not 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 `npm run dev` to restart your local environment.
- You preview a site when the site was opened with the editor menu option. Run `build` and then `release` to release a new version.

</details>

<blockquote class="tip">

**Tip:** Access to site environment data and interact with other Wix Apps, such as Wix Stores and Wix Bookings, using the [Site API](https://dev.wix.com/docs/sdk/host-modules/site/introduction.md).

</blockquote>

## Step 3 | Build and deploy your app

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

1. Run the following command to build your app:

    ```bash
    npm run build
    ```

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

    ```bash
    npm run release
    ```

An app version allows you to publish an app to the [Wix App Market](https://www.wix.com/app-market) or install it on a site with a direct install URL. You can view your [app versions](https://manage.wix.com/app-selector?title=Select+an+App&primaryButtonText=Select+Site&actionUrl=https%3A%2F%2Fdev.wix.com%2Fapps%2F%7BappId%7D%2Fversions-app) in the app dashboard.

For more information about building and deploying your app, see [Build and Deploy an App with the CLI](https://dev.wix.com/docs/wix-cli/legacy/wix-cli-for-apps/app-development/build-and-deploy-an-app-with-the-cli.md).

## Delete a site widget extension

To delete an existing site widget extension from your app, delete the subfolder under `src/site/plugins/custom-element/` that contains your site plugin's files. 

> **Note**: If you've already [created a version](https://dev.wix.com/docs/wix-cli/legacy/wix-cli-for-apps/app-development/build-and-deploy-an-app-with-the-cli.md#step-3--create-an-app-version) of your app, deleting a site widget's files from your project does not remove the site widget from your app's latest version in the app dashboard. To remove the site widget, create a new version after deleting the [site widget's files](https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/site-extensions/custom-element-site-widgets/site-widget-extension-files-and-code.md).

## See also

- [Tutorial | Create an App with Wix CLI](https://dev.wix.com/docs/build-apps/get-started/quick-start/create-an-app-with-the-wix-cli.md)
- [Tutorial | Build a Locations App Using the Wix CLI](https://dev.wix.com/docs/build-apps/get-started/tutorials/tutorial-build-a-locations-app-with-the-cli.md#tutorial--build-a-locations-app-using-the-wix-cli)