> 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: Site Plugin Extension Files and Code

## Article: Site Plugin Extension Files and Code

## Article Link: https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/site-extensions/site-plugins/site-plugin-extension-files-and-code.md

## Article Content:

# Site Plugin Extension Files and Code

<blockquote classname="note">

**CLI Documentation Notice**

We've released a [new Wix CLI](https://dev.wix.com/docs/wix-cli/guides/about-the-wix-cli.md). Continue here if your project uses the Wix CLI for Apps. [Determine which CLI your project uses](https://dev.wix.com/docs/wix-cli/guides/development/determine-which-cli-your-project-uses.md). 

</blockquote>

[Add a new site plugin](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/site-extensions/site-plugins/add-a-site-plugin-extension-in-the-cli.md) to your CLI project with the following command:

```bash
npm run generate -- --type=SITE_PLUGIN
```

The CLI generates this directory structure in your project repo:

```tsx
.
└── <your-app-name>/
    └── src/
        ├── assets/
        │   └── <your-plugin-name>/
        │       └── logo.svg
        └── site/
            └── plugins/
                └── custom-elements/
                    └── <your-plugin-name>
                        ├── panel.tsx
                        ├── plugin.json
                        ├── plugin.module.css
                        └── plugin.tsx
```

The following files are created in your site plugin's folder:

+ A `panel.tsx` file that contains the code for the site plugin's settings panel.
+ A `plugin.json` file that configures how your site plugin integrates with a Wix site. It defines the locations where the plugin can be added.
+ A `plugin.module.css` file that configures CSS styling to customize your plugin's appearance. It is generated with some initial styles to help you get started.
+ A `plugin.tsx` contains the custom element code that supports the site plugin.

A `logo.svg` file is also created in a subdirectory with your plugin's name inside your app's `/assets` folder.

It is possible to create a site plugin extension manually by adding these files yourself, but we don't recommend it for a couple of reasons:

+ You're more likely to make errors in the filepath if you add the files and folders yourself. If the filepath is incorrect, the CLI can't detect the custom element and the site plugin won't work.
+ The auto-generated files offer React template code that helps you get started developing.

## Plugin logo

A `logo.svg` file is created in a subdirectory with your plugin's name inside your app's `/assets` folder when you generate this extension. The file is used as your plugin's logo in the plugin explorer in the editor. The file isn't required, however it's referenced in the `logoUrl` field in the `plugin.json` file. 

<blockquote class="important">

__Important:__
If you rename the file, you must update the path in `logoUrl`. If you remove the file, you must remove the `logoUrl` property entirely. The file must be a square JPG, PNG, or SVG.

</blockquote>

## **plugin.json**

The `plugin.json` file configures which slots your plugin can be added to. This file is required, so don't delete it after the site plugin is generated. If you add your own files, you must include a `plugin.json`.

When you generate a new site plugin in your project, you'll see the following code in `plugin.json` (`placements` will contain the details your selected plugin slot):

```json
{
  "$schema": "https://dev.wix.com/wix-cli/schemas/site-plugin.json",
  "id": "91b609a9-bea1-446b-a21a-312c2853e020",
  "referenceComponentId": "8a82aa10-badb-435b-9c93-8c094247cb7a",
  "marketData": {
    "name": "Your Plugin Name",
    "logoUrl": "../../../../assets/<your-plugin-name>/logo.svg"
  },
  "placements": [
    {
       "appDefinitionId": "a0c68605-c2e7-4c8d-9ea1-767f9770e087",
       "widgetId": "6a25b678-53ec-4b37-a190-65fcd1ca1a63",
       "slotId": "product-page-details-1"
    }
  ],
  "installation": {
    "autoAddToSite": true
  }
}
```

The `placements` array is generated with the details of the slot you selected. You can add slots to the `placements` array to allow your plugin to be added to multiple slots. For detailed information on each available slot, see [About Slots](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/site-extensions/site-plugins/supported-wix-app-pages/about-slots.md).

By default, your file is configured so that your app will add the plugin to its slots on the site automatically upon installation.

If you have more than one placement for slots on a single page, the plugin will be added to the first slot in the array by default. Users may then manually move the plugin to their desired location in the editor.

| Field                            | Type     | Description                                                                                                                                                                                                                                                                                                                                |
|----------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `$schema`                             | string   | The URL of the schema file that provides autocomplete information for this file.                                                                                                                                                                          |
| `id`                             | string   | A unique identifier for your site plugin. The CLI generates this GUID for you. If you add the JSON file yourself, you must generate your own GUID.                                                                                                                                                                                          |
| `referenceComponentId`                           | string   | A unique identifier for your plugin's custom element . The CLI generates this GUID for you. If you add the JSON file yourself, you must generate your own GUID.                                                                                                                                                                                                   |
| `marketData.name`           | string   | The name of your plugin as it will appear in the plugin explorer in the editor and in your [app dashboard](https://manage.wix.com/account/custom-apps). |
| `marketData.logoUrl`           | string   | The relative path from your `plugin.json` to your logo file. |
| `placements`           | array   | An array of placement objects that define the slots your plugin can be added to. For detailed information on each available slot, see [About Slots](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/site-extensions/site-plugins/supported-wix-app-pages/about-slots.md).  |
| `placements.appDefinitionId`           | string   | The ID of the app the slot belongs to. |
| `placements.widgetId`           | string   | The ID of the page containing the slot. |
| `placements.slotId`           | string   | The ID of the slot your plugin can be added to. |
| `installation.autoAddToSite`           | boolean   | Whether the plugin should be added to the specified slots automatically when your app is installed on a site. |

## **plugin.tsx**

The `plugin.tsx` file is where you write the code for the custom element that defines the site plugin. You can write code in other files and include it here, but you must return your main component in this file. This is where the CLI will look for the site plugin definition.

This file is required for the site plugin to work, so don't delete it. If you add the files on your own, you must include `plugin.tsx`.

When the `plugin.tsx` file is generated, it looks like this:

```javascript
import React, { type FC } from 'react';
import ReactDOM from 'react-dom';
import reactToWebComponent from 'react-to-webcomponent';
import styles from './plugin.module.css';

type Props = {
  name: string;
};

const CustomElement: FC<Props> = (props) => {
  return (
    <div className={styles.root}>
      <h2>Hello {props.name || 'Wix CLI'}</h2>
      <p>
        Open <code>`src/site/plugins/custom-elements/{your-plugin-name}</code> to start building your plugin
      </p>
    </div>
  );
};

const customElement = reactToWebComponent(
  CustomElement,
  React,
  ReactDOM as any,
  {
    props: {
      name: 'string',
    },
  }
);

export default customElement;
```

The file sets up a React component named `CustomElement` where you write the custom element code. It also calls `reactToWebComponent` to convert your React component to a custom element, and exports the custom element so Wix can work with it as a widget.

When using `reactToWebComponent`, attribute updates are automatically reflected in your plugin in the editor. To manually handle attribute updates so they are reflected in your widget in the editor, use [`attributeChangedCallback()`](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#responding_to_attribute_changes) in your custom element's code.

Note that you don't need to call `define()` even here; Wix still takes care of that for you even if you haven't defined the custom element in React.

### Slot data

Each slot supports an API that provides data about the plugin's context (for example the `productId` of the current product on the Product page). This data is available to your site plugin in the props passed to your custom element.

These properties are listed in the [documentation](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/site-extensions/site-plugins/supported-wix-app-pages/about-slots.md) for each slot.

In your code, you first need to define the prop. This is done in the same way the `name` prop is defined in `plugin.tsx`. For example:

```javascript
type Props = {
  name: string;
  productId: string;
};
```

You can then access the prop's data in your custom element code in the same way we do for `name`. For example:

```javascript
const CustomElement: FC<Props> = (props) => {
  return (
    <div className={styles.root}>
      <h2>Hello {props.name || 'Wix CLI'}</h2>
      <p>
        Open <code>`src/site/plugins/custom-elements/my-site-plugin`</code> to start
        building your plugin
      </p>
      <p>Your productId is {props.productId || `Unknown`}</p>
    </div>
  );
};
```

To get updates from the custom element, you need to register for them in the same way we do for `name`. For example:

```javascript
const customElement = reactToWebComponent(
  CustomElement,
  React,
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  ReactDOM as any,
  {
    props: {
      name: 'string',
      productId: 'string',
    },
  }
);
```

## **panel.tsx**

The `panel.tsx` file contains the code defining your site plugin's settings panel. The settings panel lets site users customize the plugin after they install your app. You're not required to include the `panel.tsx` file. However, without this file your site plugin won't have a settings panel.

When the `plugin.tsx` file is generated, it looks like this:

```javascript
import React, { type FC, useState, useEffect } from 'react';
import { widget } from '@wix/editor';
import {
  SidePanel,
  WixDesignSystemProvider,
  Input,
  FormField,
} from '@wix/design-system';
import '@wix/design-system/styles.global.css';

const Panel: FC = () => {
  const [name, setName] = useState<string>('');

  useEffect(() => {
    widget.getProp('name').then(name => setName(name || 'Wix CLI'));
  }, [setName]);

  return (
     <WixDesignSystemProvider>
       <SidePanel width="300">
         <SidePanel.Content noPadding stretchVertically>
           <SidePanel.Field>
             <FormField label="Your name">
               <Input
                 type="text"
                 value={name}
                 onChange={(event) => {
                   const newName = event.target.value;
                   setName(newName);
                   widget.setProp('name', newName);
                 }}
               />
             </FormField>
           </SidePanel.Field>
         </SidePanel.Content>
       </SidePanel>
     </WixDesignSystemProvider>
   );
};

export default Panel;
```

The file contains a React component called `Panel` where you write your code defining the plugin's settings panel.
`WixDesignSystemProvider` wraps the child components to align them with Wix's design conventions.

The file also contains a `useEffect` hook to fetch and set the initial value of the `name` property from the plugin's properties when the component mounts.

As with `plugin.tsx`, you can write code in other files and include it here, but you must return your main component in this file. The panel code must be written in React to work with the rest of the CLI.

You can manage the properties of your site plugin's custom element using the [Widget API](https://dev.wix.com/docs/sdk/host-modules/editor/widget/introduction.md). You can also use Wix's [JavaScript SDK](https://dev.wix.com/docs/sdk.md) in the panel’s code to [retrieve environmental data from the editor](https://dev.wix.com/docs/sdk/host-modules/editor/info/introduction.md) and access and manage Wix business solutions.

To apply changes made in the settings panel to the plugin, use the Widget API’s [`setProp()`](https://dev.wix.com/docs/sdk/host-modules/editor/widget/set-prop.md) function. Widget properties are bound to your custom element’s attributes, so any change in the properties automatically updates the corresponding attribute.

Learn more about [creating a settings panel for a site plugin built with the CLI](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/site-extensions/site-widgets/create-a-settings-panel-for-a-site-widget-or-plugin-wix-cli-and-self-hosting.md).