Add Event Extensions with the CLI

Events are triggered when specific conditions on your app or a user’s site are met. Wix Apps can respond to these events using event extensions created in the CLI. Events in the CLI are built on Javascript SDK webhooks, and event extensions subscribe your app to these webhooks behind the scenes.

For more information about events, read About Events.

Follow the instructions below to:

1. Create an event extension for your app.
2. Add permissions requirements to your app.
3. Test the event extension on a site.
4. Deploy your app with the event extension.

Once this task is complete, your app will have an event extension that is triggered when a specific event occurs on a site.

Before you begin

• You must have an app project that was created using the Wix CLI.
• You must be logged into your Wix Developer account. If you don’t have one, sign up for a Wix Developer account.

Step 1 | Create the extension

In the terminal:

1. Navigate to your project repo.

2. Run the following command:

   Copy

3. The CLI will display a menu of extensions to generate. Select Event and hit enter to continue.

4. The CLI will prompt you to name your event folder. This is the name of the folder in the project repo that contains the event code, and the name of the event in the app dashboard. Only you will see this name.

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

event.ts

This file is required and must contain:

• The relevant import statement for the event.
• An event function where you can implement your custom logic. Wix calls this function when the given event occurs, passing the event object and its metadata. Event functions are documented in their module in the Javascript SDK reference.

The generated event.ts file will contain example code for an event.

The event.ts file must be in the following format:

For example, an event.ts for the Wix CRM onContactCreated() event should look like this:

Step 2 | Add permissions requirements to your app

To work an event your app must have the required permissions for that event. You must configure your app in the app dashboard to request those permissions when installed.

The required permission scopes for an event are listed in the documentation for that event's webhook in the SDK reference. For example, to work with the Wix CRM onContactCreated(), your app could request the MANAGE MEMBERS AND CONTACTS - ALL PERMISSIONS permission scope.

To configure permissions requirements for your app:

1. Go to the Permissions page in your app's dashboard.
2. Click Add Permissions.
3. Click Search by name or ID and enter the name of the permission scope you selected.
4. The permission scope will appear under Choose Permission Scopes. Click the checkbox next to it, and then click Save.

Step 3 | Test your event extension

To test your event extension, you must:

1. Add logging inside your backend logic.
2. Trigger the event.
3. View the logs in the terminal.

Add logging inside your backend logic

Inside your event.ts file, add a console.log() command to one of your functions. For example:

Trigger the event

The process for triggering an event depends on the type of event:

• Events that can be triggered by actions on a site or its dashboard can be triggered in the CLI's local development environment, in which case logs will be displayed in the CLI.
• Events that can't be triggered by actions on a site or dashboard cannot currently be tested with the CLI.

To trigger to the event in the local development environment, you must navigate to the site or its dashboard in your local development environment, then take an action will trigger your event.

1. From your app's directory in the terminal, run the following command:

   Copy

2. Press D to open a dashboard page of your development site in your browser.

3. If you can take an action to trigger your event in the dashboard, do so. Otherwise, proceed to the next step.

4. Navigate to the Home tab in the dashboard sidebar.

5. Click the three dots and then click View live site as shown in the image below.
   
   

6. Take an action will trigger your event. This action depends on your specific event.

View the logs in the terminal

Navigate back to the CLI terminal and you will see the logs from your backend logic in the following form:

Step 4 | Build and deploy your app

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

1. Run the following command to build your app:

   Copy

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

   Copy

An app version allows you to publish an app to the Wix App Market or install it on a site with a direct install URL.

For more information about building and deploying your app, see Build and Deploy an App with the CLI.

Delete an event extension

To delete an event extension from your app, simply delete the subfolder under src/backend/events that contains your event extension's files.