wix-cli-backend-event

Wix CLI Backend Event Extension

Creates event extensions for Wix CLI applications. Events are triggered when specific conditions occur—on a Wix user's site for app projects, or on your project's site for headless projects. Your project responds using event extensions built on JavaScript SDK webhooks; the CLI subscribes your project to these webhooks.

Common use cases: run logic when a contact is created, an order is placed, a booking is confirmed, or a blog post is published.

Quick Start Checklist

Follow these steps in order when creating an event extension.

1. Create event folder: src/extensions/backend/events/<event-name>/
2. Create <event-name>.ts with the SDK event import and handler function
3. Create <event-name>.extension.ts with extensions.event() and a unique UUID
4. Update src/extensions.ts to import and use the new extension

User (manual): Configure app permissions for the event in the app dashboard if required; release a version and trigger the event to test.

References

Topic	Reference
Common events (CRM, eCommerce, Bookings, Blog)	COMMON-EVENTS.md

Output Structure

Two files per event (docs). Only one handler per event allowed in the app (including dashboard handlers).

src/extensions/backend/events/<event-name>/
├── <event-name>.extension.ts   # Builder: extensions.event({ id, source }) – id is unique GUID
└── <event-name>.ts             # Handler: imports SDK event (e.g. onContactCreated), runs on trigger

Implementation Pattern

Event builder (<event-name>.extension.ts)

Use extensions.event() from @wix/astro/builders. Required fields: id (unique GUID), source (path to the handler file).

import { extensions } from "@wix/astro/builders";

export const eventContactCreated = extensions.event({
  id: "{{GENERATE_UUID}}",
  source: "./extensions/backend/events/contact-created/contact-created.ts",
});

CRITICAL: UUID Generation

The id must be a unique, static UUID v4 string. Generate a fresh UUID for each extension—do NOT use randomUUID() or copy UUIDs from examples. Replace {{GENERATE_UUID}} with a freshly generated UUID like "a1b2c3d4-e5f6-7890-abcd-ef1234567890".

Event handler (<event-name>.ts)

Import the event from the correct SDK module and pass a handler. Wix invokes the handler with the event payload and metadata when the event occurs. Handler signatures are documented in the JavaScript SDK reference.

import { onContactCreated } from "@wix/crm/events";

onContactCreated((event) => {
  console.log("Contact created:", event.entity);
  // Custom logic: sync to CRM, send welcome email, etc.
});

Handler can be async; ensure errors are caught and logged so one failing handler does not break others.

Extension Registration

Two steps required.

Step 1: Event builder file

Create <event-name>.extension.ts inside the event folder (and <event-name>.ts for the handler) as shown in Implementation Pattern above.

Step 2: Register in main extensions.ts

CRITICAL: Read wix-cli-extension-registration and add the event extension to src/extensions.ts (import and .use(eventContactCreated) or equivalent). Without this, the event extension is not active.

Naming: export names follow event{CamelCaseName} (e.g. eventContactCreated, eventOrderPaid).

Elevating Permissions for API Calls

When calling Wix APIs from inside an event handler, use auth.elevate from @wix/essentials so the call runs with the right permissions.

import { auth } from "@wix/essentials";
import { items } from "@wix/data";

onContactCreated(async (event) => {
  const elevatedQuery = auth.elevate(items.query);
  const result = await elevatedQuery("MyCollection").find();
  // Use result
});

Key Constraints

• One handler per event – You cannot have two event extensions for the same event in the app (local or dashboard).
• Permissions – Each event may require specific permission scopes; configure them in the app dashboard (Permissions page).
• Testing – Release a version with your changes, then perform the action that triggers the event. Some events are not fully testable in local dev.
• Backend limits – Event handlers run under backend extension limits (e.g. 1000 CPU ms per request, 20 sub-requests). See About Backend Extensions.

Best Practices

• Error handling: Wrap handler logic in try/catch; log and optionally rethrow or report.
• Idempotency: Events may be delivered more than once; design handlers to be idempotent where possible.
• Logging: Use console.log for debugging; keep production logs minimal and non-sensitive.
• Performance: Finish within backend limits; offload heavy work to queues or background jobs if needed.

Testing Event Extensions

1. Release a version with your changes.
2. Trigger the event by taking an action.