> 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 Custom Element Extension

## Article: Add a Custom Element Site Widget Extension with the Wix CLI

## Article Link: https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/custom-elements/add-a-custom-element-extension.md

## Article Content:

# Add a Custom Element 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, see [About Site Widget Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/site-extensions/site-widgets/about-site-widget-extensions.md)

Custom element site widgets extensions are 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 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](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/generate.md) command.

    The CLI will display a menu of extensions to generate. Select **Site Widget** and hit enter. 
    
3. When prompted, choose **Custom Element** as your framework.

    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:

```bash
src/
  └── extensions/
      └── site/
          └── widgets/
              └── <your-widget-name>/
                  ├── <your-widget-name>.extension.ts
                  ├── <your-widget-name>.tsx
                  ├── <your-widget-name>.panel.tsx
                  ├── <your-widget-name>.module.css
                  └── thumbnail.png
```

> **Note:** This is the default folder structure created by the CLI. You can move these files to any location within the `src/` folder and update the references in your `extension.ts` file. Learn more about the [flexible file system](https://dev.wix.com/docs/wix-cli/guides/get-started/project-structure.md#your-custom-extension-folder).

Learn more about the [Custom Element site widget extension files](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/custom-elements/custom-element-extension-files-and-code.md).

## Step 2 | Test your site widget

You can test your site widget while you're developing by running the [dev](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/dev.md) 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.

<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 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](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/dev.md) command to restart your local environment.
- You preview a site when the site was opened with the editor menu option. Run the [build](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/build.md) command and then the [release](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/release.md) command 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 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](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/build.md) command.

2. Run the [release](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/release.md) command and follow the prompts to release an app version.

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 Wix CLI](https://dev.wix.com/docs/wix-cli/guides/development/build-and-deploy-a-project.md).

You can control whether your site widget is added to a site automatically when a site owner installs your app. Set **`installation.autoAdd`** in your widget's extension file (`element.extension.ts`): `true` adds the widget to the site home page on install; `false` leaves it out (the site owner adds it from the editor's **Add** panel). In the CLI, automatic installation applies only to the home page—not to master pages (header/footer) or all pages. For details, configuration examples, and best practices, see [About site widget installation with the CLI](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/site-widgets/about-site-widget-installation-with-the-cli.md).

## 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`](https://dev.wix.com/docs/wix-cli/guides/extensions/about-the-extensions-ts-file.md) file.

> **Note**: If you've already created a version of your app, deleting a site widget's files from your project doesn't 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 extension files.