Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Wix Design System (WDS)

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

# Migrate an Event Extension

Add an event extension to your new Wix CLI project as part of [migrating an app from the legacy Wix CLI](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/migrate-an-app-to-the-new-cli/migrate-an-app-from-the-legacy-cli/migrate-a-legacy-cli-app-to-the-new-wix-cli).

## Folder structure

| Legacy path | New path |
|--------|-----|
| `src/backend/events/<name>/event.ts` | `src/extensions/backend/events/<name>/<name>.ts` |
| None | `src/extensions/backend/events/<name>/<name>.extension.ts` |

> **Note:** `<name>` is your extension's folder name in the legacy project. The new folder and files use the same name.

## Step 1 | Copy and rename the file

In the new project:

1. Create the folder `src/extensions/backend/events/<name>/`.
2. From the legacy project's `src/backend/events/<name>/` folder, copy `event.ts` into the new folder, and rename it to `<name>.ts`.

## Step 2 | Adapt the code to the new project

In `<name>.ts`:

1. Add `export default` before the top-level handler call if it isn't already there:

    ```ts
    // Before
    myModule.onSomeEvent((event) => { ... });

    // After
    export default myModule.onSomeEvent((event) => { ... });
    ```

2. Update any imports as needed, to use the new paths, including imports of backend code.

## Step 3 | Create the extension file

In the new project:

1. In `src/extensions/backend/events/<name>/`, create `<name>.extension.ts`.
2. Add the following code, and set each field to the value the table below specifies:

    ```ts
    import { extensions } from '@wix/custom-extensions';

    export default extensions.event({
      id: '<value>',
      source: './extensions/backend/events/<name>/<name>.ts',
    });
    ```

    | Field | Source in legacy project | What to specify |
    |-------|--------------------------|-----------------|
    | `id` | None | The ID of the webhook component in your app's released version, or a new UUID if the event has never been released. See [Get the event ID](fallback::#get-the-event-id). |
    | `source` | None | Path to `<name>.ts`, relative to `src/` |

<blockquote class="caution">

__Caution:__
Once your project contains a backend event, changes to your event handlers deploy to production as soon as you release, and take effect without waiting for sites to take a new version. The CLI warns you about this at release time. Test a handler on a development site before releasing it.

This applies to the handler's code. Adding an event your app hasn't released before is a change to your app's webhooks, so it reaches each site according to the app version that site has. See [About Webhooks](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/api-integrations/events-and-webhooks/about-webhooks).

</blockquote>

### Get the event ID

The `id` depends on whether your app has already released a version containing this event.

::::tabs

:::Event-already-released

Use the ID of the webhook component that your app's released version registered for the event.

<blockquote class="caution">

__Caution:__
A new ID fails the release with a `DUPLICATE_SLUG` error. A webhook's slug is the event name, so your app would end up with 2 components for the same event.

</blockquote>

Legacy event extensions have no config file, and the legacy CLI assigns the webhook component a new ID on every build. The registered ID is therefore in the build output of the build you released. In that build's `dist/devcenter/app-manifest.json`, find the component whose `compType` is `WEBHOOK` and whose `compName` is your event name, for example `wix.contacts.v4.contact_created`, and specify its `compId` as the `id` in `<name>.extension.ts`. Building the legacy project again doesn't give you that ID, because the new build assigns a new one.

:::

:::Event-never-released

Generate a new UUID and use it as the extension's permanent ID:

1. In a terminal, run the following command:

    ```bash
    node -e "console.log(crypto.randomUUID())"
    ```

2. Copy the UUID from the terminal output, and specify it as the `id` in `<name>.extension.ts`.

Once you release a version containing the event, this ID identifies its component in your app, so later releases must keep using it.

:::

::::

## Step 4 | Register the extension

In the new project, in `src/extensions.ts`:

1. Import the extension:

    ```ts
    import myEvent from './extensions/backend/events/<name>/<name>.extension';
    ```

2. Add a `.use()` call for it to the `app()` chain, on its own line:

    ```ts
    .use(myEvent)
    ```

## Step 5 | Return to the main migration guide

Return to [Install the extension's dependencies](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/migrate-an-app-to-the-new-cli/migrate-an-app-from-the-legacy-cli/migrate-a-legacy-cli-app-to-the-new-wix-cli#install-the-extensions-dependencies) in the main migration guide.