Add Event Extensions with the Wix CLI for Headless

This feature is in Developer Preview and is subject to change.

Events are triggered when specific conditions occur in your Headless project. Your project can respond to these events using event extensions. Events in the CLI for Headless are built on Javascript SDK webhooks, and event extensions subscribe your project to these webhooks behind the scenes.

Learn more about event extensions.

Follow the instructions below to:

  1. Create an event extension for your project.
  2. Test the event extension in your project.
  3. Deploy your project with the event extension.

Once this task is complete, your project will have an event extension that's triggered when a specific event occurs.

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 your project. Only you will see this name.

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

Copy

event.json

The extension.json file contains the event extension's configuration details. This file defines event triggers the extension's code. The structure is as follows:

Copy
FieldTypeDescription
compIdstringUnique component ID. Must be unique across all extensions in the project.
compTypestringAlways WEBHOOK for event extensions.
compNamestringThe event name/slug.
compData.webhook.webhookSlugstringThe event slug that triggers the extension.

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:

Copy

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

Copy

Step 2 | Test your event extension

Important: Currently, local development is not supported for all events in the CLI for Headless. If you are unable to test your event in the local development environment as described in this step, you can still see it in action by pushing your changes to production. See Step 4 | Build and deploy your project..

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:

Copy

Trigger the event

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

  • Events that can be triggered by actions in your project's 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 in your project's dashboard can't currently be tested with the CLI for Headless.

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

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

    Copy
  2. Click the link to open your project's dashboard or site in your browser, depending on where you need to trigger the event.

  3. Take an action that 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:

Copy

Note: You can't view logs from backend code in production.

Step 4 | Build and deploy your project

Once your project is ready for production, you can build it and release your project.

  1. Run the following command to build your project:

    Copy
  2. Run the following command and follow the prompts to release your project:

    Copy

For more information about building and deploying your project, see Build and Deploy a Project with the Wix CLI for Headless.

Delete an event extension

To delete an event extension from your project, delete the subfolder under src/extensions that contains your event extension's files.

See also

Did this help?