> 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: Migrate a Custom Element Extension

## Article: Migrate a Custom Element Extension

## Article Link: https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/migrate-an-app-from-legacy-cli/migrate-a-custom-element-extension.md

## Article Content:

# Migrate a Custom Element Extension

This guide explains how to add a custom element extension to your new Wix CLI project as part of [migrating an app from the legacy Wix CLI](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/about-the-wix-cli.md).

## Folder structure

| Legacy | New |
|--------|-----|
| `src/site/widgets/custom-elements/<name>/element.json` | `src/extensions/site/widgets/<name>/<name>.extension.ts` |
| `src/site/widgets/custom-elements/<name>/element.tsx` | `src/extensions/site/widgets/<name>/<name>.tsx` |
| `src/site/widgets/custom-elements/<name>/panel.tsx` | `src/extensions/site/widgets/<name>/<name>.panel.tsx` |
| `src/site/widgets/custom-elements/<name>/plugin.module.css` | `src/extensions/site/widgets/<name>/<name>.module.css` |

> **Note:** The `custom-elements/` wrapper directory is removed in the new structure. Files move up 1 level to `src/extensions/site/widgets/<name>/`.

## Step 1 | Move and rename files

To move existing files into the new project:

1. In the new project, create the folder `src/extensions/site/widgets/<name>/`.
2. Copy and rename the files:
   - `element.tsx` → `<name>.tsx`
   - `panel.tsx` → `<name>.panel.tsx`
   - `plugin.module.css` → `<name>.module.css` (if present)
3. Update import references in the `.tsx` files to use the new filenames.
4. Fix any other import paths in the `.tsx` files if needed, including imports of backend code.

Don't copy the old `element.json` file. It is replaced by a new `.extension.ts` file.

## Step 2 | Create the extension file

In `src/extensions/site/widgets/<name>/`, create `<name>.extension.ts`:

```ts
import { extensions } from '@wix/astro/builders';

export default extensions.customElement({
  id: '<id-from-element.json>',
  name: '<name-from-element.json>',
  width: {
    defaultWidth: 300,
    allowStretch: false,
    stretchByDefault: false,
  },
  height: {
    defaultHeight: 300,
  },
  installation: {
    autoAdd: false,
  },
  tagName: '<name>',
  element: './extensions/site/widgets/<name>/<name>.tsx',
  settings: './extensions/site/widgets/<name>/<name>.panel.tsx',
});
```

| Field | Source | Required |
|-------|--------|----------|
| `id` | `id` from `element.json` | Yes. Must match legacy value to preserve the extension. |
| `name` | `name` from `element.json` | Yes |
| `width` | `width` from `element.json`. Use defaults if not set. | Yes |
| `height` | `height` from `element.json`. Use defaults if not set. | Yes |
| `installation.autoAdd` | `installation.autoAddToSite` or `installation.autoAdd` from `element.json` | Yes. Use `false` if not set. |
| `installation.essential` | `installation.essential` from `element.json` | No |
| `presets` | `presets` array from `element.json` | No |
| `tagName` | Use the extension folder name | Yes |
| `element` | Path to `<name>.tsx`, relative to `src/` | Yes |
| `settings` | Path to `<name>.panel.tsx`, relative to `src/` | Yes |

<blockquote class="important">

__Important:__
The `id` must match the value from the legacy `element.json`. Otherwise, the new entry is treated as a separate extension instead of a continuation of the legacy one.

</blockquote>

### Preset thumbnail URLs

If the legacy `element.json` has presets with thumbnail URLs that reference a local `assets/` folder, replace them with `{{BASE_URL}}/thumbnail.png`:

```ts
presets: [
  {
    id: '<preset-id>',
    name: '<preset-name>',
    thumbnailUrl: '{{BASE_URL}}/thumbnail.png',
  },
],
```

## Step 3 | Register the extension

In the new project, in `src/extensions.ts`, import the extension and add it with `.use()`:

```ts
import { app } from '@wix/astro/builders';
import myCustomElement from './extensions/site/widgets/<name>/<name>.extension';

export default app().use(myCustomElement);
```

## Step 4 | Return to the main migration guide

Return to the [Test, build, and release](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/about-the-wix-cli.md#test-build-and-release) step in the main migration guide.