How to run backend code on Wix events in Studio Two

4 days ago

3 min read

Updated: 2 days ago

In Studio Two, add a Backend Events extension from the Code tab through the Wix Extension Builder. The Builder generates a configuration file and an event handler. Wix calls the handler whenever the matching platform event fires, for example when a contact is created.

Before you start

A Studio Two site project with access to the Code tab.
Access to the site dashboard, to check logs under Developer Tools.
The npm package for the event you listen to. The Contact Created example needs @wix/crm.
Wix Studio and Wix Editor sites do not use this extension. They use Velo backend event handlers.

Step by step

Open the Wix Extension Builder. In the Studio Two editor, open the Code tab. In the VS Code sidebar, open the Wix Extension Builder.
Generate the extension. Under Create an Extension, pick Backend, then Backend Events. Enter an event folder name (lowercase letters, numbers and hyphens only) and click Generate.
Find the generated files. The files are in src/extensions/backend/events/<event-folder>/. The Builder also registers the extension in extensions.ts and lists it under My Extensions.
Leave the configuration file alone. <event-folder>.extension.ts holds the configuration. Keep the generated id. The source value is the path to the handler, relative to src/.
Install the package for your event. The generated handler imports contacts from @wix/crm, which a new project does not include. Run npm install @wix/crm in the terminal of the Code tab.
Add the event permission. Wix needs a permission on the event before it calls the handler. The header of the generated file links the permission for the Contact Created event. Add it before you test.
Write the handler logic. Open <event-folder>.ts and replace the placeholder comment with your logic. To log that the handler ran, import monitoring from @wix/essentials and call it inside the handler. Save the file.
Switch to another event if needed. To listen to a different event, change the import and the handler method, for example replace contacts.onContactCreated with another event method. The API reference lists the events and their payloads.
Trigger the event and check the logs. For Contact Created, create a contact under Customers & Leads > Contacts in the dashboard, or submit a form on the live site. Then open Developer Tools > Logs and look for your entry.
Publish the site. Click Publish in the Studio Two editor. This ships the extension with your site.

Good to know

The handler runs without a visitor or member identity. Use elevation to call Wix APIs that need permissions.
A handler writes no log entry by itself. console output does not appear in your site's logs, so use monitoring from @wix/essentials.
The handler can run more than once for the same event. Make it safe to repeat, for example check whether a record exists before you create one.
The event object passed to the handler has fields that depend on the event. Check the API reference for each payload.
You can also ask Aria, the Wix AI assistant, or the AI in the Code tab to create or customize the extension.

parnii note

Make the handler idempotent from the start, because repeated delivery is possible. Check the permission and the npm package before you debug the handler itself, since a missing permission means Wix will not call it.

FAQ

Where do I add a Backend Events extension in Studio Two?

In the Code tab. Open the Wix Extension Builder in the VS Code sidebar, then choose Backend and Backend Events under Create an Extension.

Why does console.log not show up in my Wix site logs?

Studio Two does not send console output to your site's logs. Use the monitoring client from @wix/essentials inside the handler, then check Developer Tools > Logs in the dashboard.