Create an event

In this guide, we will cover the creation of server event and how to implement them in your pages, we will create a new domain event that will be emitted when a customer votes on an FAQ question.

What is an event emitter

The events are dispatched through the use of an event emitter. The role of the event emitter is to push events to the server event pipeline to be processed by the server.

Prerequisites

Before diving into the code, ensure you have the following prerequisites in place:

• A Front-Commerce project configured and ready to use

info

The outcome of this guide is already available in the FAQ example extension.

Create a Domain event class

Let's create a file in our project, called QuestionVotedEvent.ts:

app/server-events/events/QuestionVotedEvent.ts

import { ServerEvent } from "@front-commerce/core/events";

const QuestionVotedEventName = "QuestionVotedEvent";

// This is the payload data that we want to gather for the event
type QuestionVotedEventPayload = {
  questionSlug: string;
  upvote: boolean;
};

// We define an event class that extends the ServerEvent class
// This class will contain data to be pushed to the server event pipeline
export default class QuestionVotedEvent extends ServerEvent<QuestionVotedEventPayload> {
  static event_type = QuestionVotedEventName;

  // See https://developers.front-commerce.com/docs/3.x/api-reference/front-commerce-core/ServerEvent#arguments
  constructor(questionSlug: string, upvote: boolean, shopId: string) {
    super(
      QuestionVotedEventName,
      new Date(),
      { questionSlug, upvote },
      // This are the event metadata, you can use it to set infos about the event
      // which are not part of the event payload
      { shopId }
    );
  }
}

info

You can check the ServerEvent API Reference out to learn more about the usage of ServerEvent class.

Use the Event

Now that we've created a Domain event class, let's use it in a route's action:

app/routes/_main.faq.$slug.tsx

//...
export const action = async ({
  context,
  params,
  request,
}: ActionFunctionArgs) => {
  const { slug } = params;

  const app = new FrontCommerceApp(context.frontCommerce);
  // ... Here should be the "voting" mechanism (probably a mutation)

  // We call the `ServerEventBus` to dispatch an event.
  // In this example, we use it to dispatch a `QuestionVotedEvent` event created above.
  app.services.ServerEventBus.publish(
    new QuestionVotedEvent(
      String(slug),
      formData.get("isFaqUseful") === "true",
      app.config.currentShopId
    )
  );

  // ... The rest of the action, return, etc.
};
//...

Test our emitter

Now that everything is ready, let's test it! To do so, start the Front-Commerce Worker by running:

pnpm run worker

The worker will boot:

2024-02-23 14:55:21 [info]:     Font-Commerce Server Events Worker
2024-02-23 14:55:21 [info]:     Please wait booting...
2024-02-23 14:55:24 [info]:     Worker started

And now let's head to the faq question page: http://localhost:4000/faq/probleme-colis and vote.

You will see new output to the worker:

[ConsoleIntegration]: (1708696560088-0) {"event_type":"QuestionVotedEvent","created_at":"2024-02-23T13:56:00.080Z","payload":"{\"questionSlug\":\"probleme-colis\",\"upVote\":true}","metadata":"{\"shopId\":\"default\"}"}

And that's it! You now know how to create and emit your own server events.