Skip to main content

Create Events Module

In this document, you’ll learn how to create an events module.

Overview

Medusa provides ready-made modules for events, including the local and Redis modules. If you prefer another technology used for managing events, you can build a module locally and use it in your Medusa backend. You can also publish to NPM and reuse it across multiple Medusa backend instances.

In this document, you’ll learn how to build your own Medusa events module, mainly focusing on creating the event bus service and the available methods you need to implement within your module.


(Optional) Step 0: Prepare Module Directory

Before you start implementing your module, it's recommended to prepare the directory or project holding your custom implementation.

You can refer to the Project Preparation step in the Create Module documentation to learn how to do that.


Step 1: Create the Service

Create the file services/event-bus-custom.tsCopy to Clipboard which will hold your event bus service. Note that the name of the file is recommended to be in the format event-bus-<service_name>Copy to Clipboard where <service_name>Copy to Clipboard is the name of the service you’re integrating. For example, event-bus-redisCopy to Clipboard.

Add the following content to the file:

services/event-bus-custom.ts
import { EmitData, EventBusTypes } from "@medusajs/types"
import { AbstractEventBusModuleService } from "@medusajs/utils"

class CustomEventBus extends AbstractEventBusModuleService {
async emit<T>(
eventName: string,
data: T,
options: Record<string, unknown>
): Promise<void>;
async emit<T>(data: EmitData<T>[]): Promise<void>;
async emit(
eventName: unknown,
data?: unknown,
options?: unknown
): Promise<void> {
throw new Error("Method not implemented.")
}
}

export default CustomEventBus
Report Incorrect CodeCopy to Clipboard

This creates the class CustomEventBusCopy to Clipboard that implements the AbstractEventBusModuleServiceCopy to Clipboard class imported from @medusajs/utilsCopy to Clipboard. Feel free to rename the class to what’s relevant for your event bus service.

In the class you must implement the emitCopy to Clipboard method. You can optionally implement the subscribeCopy to Clipboard and unsubscribeCopy to Clipboard methods.


Step 2: Implement Methods

Note About the eventToSubscribersMap Property

The AbstractEventBusModuleServiceCopy to Clipboard implements two methods for handling subscription: subscribeCopy to Clipboard and unsubscribeCopy to Clipboard. In these methods, the subscribed handler methods are managed within a class property eventToSubscribersMapCopy to Clipboard, which is a JavaScript Map. They map keys are the event names, whereas the value of each key is an array of subscribed handler methods.

In your custom implementation, you can use this property to manage the subscribed handler methods. For example, you can get the subscribers of a method using the getCopy to Clipboard method of the map:

const eventSubscribers = 
this.eventToSubscribersMap.get(eventName) || []
Report Incorrect CodeCopy to Clipboard

Alternatively, you can implement custom logic for the subscribeCopy to Clipboard and unsubscribeCopy to Clipboard events, which is explained later in this guide.

constructor

The constructorCopy to Clipboard method of a service allows you to prepare any third-party client or service necessary to be used in other methods. It also allows you to get access to the module’s options which are typically defined in medusa-config.jsCopy to Clipboard, and to other services and resources in the Medusa backend using dependency injection.

Here’s an example of how you can use the constructorCopy to Clipboard to store the options of your module:

services/event-bus-custom.ts
class CustomEventBus extends AbstractEventBusModuleService {
protected readonly moduleOptions: Record<string, any>

constructor({
// inject resources from the Medusa backend
// for example, you can inject the logger
logger,
}, options) {
super(...arguments)
this.moduleOptions = options
}

// ...
}
Report Incorrect CodeCopy to Clipboard

emit

The emitCopy to Clipboard method is used to push an event from Medusa into your messaging system. Typically, the subscribers to that event would then pick up the message and execute their asynchronous tasks.

The emitCopy to Clipboard method has two different signatures:

  1. The first signature accepts three parameters. The first parameter is eventNameCopy to Clipboard being a required string indicating the name of the event to trigger. The second parameter is dataCopy to Clipboard being the optional data to send to subscribers of that event. The third optional parameter optionsCopy to Clipboard which can be used to pass options specific to the event bus.
  2. The second signature accepts one parameter, which is an array of objects having three properties: eventNameCopy to Clipboard, dataCopy to Clipboard, and optionsCopy to Clipboard. These are the same as the parameters that can be passed in the first signature. This signature allows emitting more than one event.

The optionsCopy to Clipboard parameter depends on the event bus integrating. For example, the Redis event bus accept the following options:

services/event-bus-custom.ts
type JobData<T> = {
eventName: string
data: T
completedSubscriberIds?: string[] | undefined
}
Report Incorrect CodeCopy to Clipboard

You can implement your method in a way that supports both signatures by checking the type of the first input. For example:

services/event-bus-custom.ts
class CustomEventBus extends AbstractEventBusModuleService {
// ...
async emit<T>(
eventName: string,
data: T,
options: Record<string, unknown>
): Promise<void>;
async emit<T>(data: EmitData<T>[]): Promise<void>;
async emit<T>(
eventOrData: string | EmitData<T>[],
data?: T,
options: Record<string, unknown> = {}
): Promise<void> {
const isBulkEmit = Array.isArray(eventOrData)

// emit event
}
}
Report Incorrect CodeCopy to Clipboard

(optional) subscribe

As mentioned earlier, this method is already implemented in the AbstractEventBusModuleServiceCopy to Clipboard class. This section explains how you can implement your custom subscribe logic if necessary.

The subscribeCopy to Clipboard method attaches a handler method to the specified event, which is run when the event is triggered. It is typically used inside a subscriber class.

The subscribeCopy to Clipboard method accepts three parameters:

  1. The first parameter eventNameCopy to Clipboard is a required string. It indicates which event the handler method is subscribing to.
  2. The second parameter subscriberCopy to Clipboard is a required function that performs an action when the event is triggered.
  3. The third parameter contextCopy to Clipboard is an optional object that has the property subscriberIdCopy to Clipboard. Subscriber IDs are useful to differentiate between handler methods when retrying a failed method. It’s also useful for unsubscribing an event handler. Note that if you must implement the mechanism around assigning IDs to subscribers when you override the subscribeCopy to Clipboard method.

The implementation of this method depends on the service you’re using for the event bus:

services/event-bus-custom.ts
class CustomEventBus extends AbstractEventBusModuleService {
// ...
subscribe(
eventName: string | symbol,
subscriber: EventBusTypes.Subscriber,
context?: EventBusTypes.SubscriberContext): this {
// TODO implement subscription
}
}
Report Incorrect CodeCopy to Clipboard

(optional) unsubscribe

As mentioned earlier, this method is already implemented in the AbstractEventBusModuleServiceCopy to Clipboard class. This section explains how you can implement your custom unsubscribe logic if necessary.

The unsubscribeCopy to Clipboard method is used to unsubscribe a handler method from an event.

The unsubscribeCopy to Clipboard method accepts three parameters:

  1. The first parameter eventNameCopy to Clipboard is a required string. It indicates which event the handler method is unsubscribing from.
  2. The second parameter subscriberCopy to Clipboard is a required function that was initially subscribed to the event.
  3. The third parameter contextCopy to Clipboard is an optional object that has the property subscriberIdCopy to Clipboard. It can be used to specify the ID of the subscriber to unsubscribe.

The implementation of this method depends on the service you’re using for the event bus:

services/event-bus-custom.ts
class CustomEventBus extends AbstractEventBusModuleService {
// ...
unsubscribe(
eventName: string | symbol,
subscriber: EventBusTypes.Subscriber,
context?: EventBusTypes.SubscriberContext): this {
// TODO implement subscription
}
}
Report Incorrect CodeCopy to Clipboard

Step 3: Export the Service

After implementing the event bus service, you must export it so that the Medusa backend can use it.

Create the file index.tsCopy to Clipboard with the following content:

services/event-bus-custom.ts
import { ModuleExports } from "@medusajs/modules-sdk"

import { CustomEventBus } from "./services"

const service = CustomEventBus

const moduleDefinition: ModuleExports = {
service,
}

export default moduleDefinition
Report Incorrect CodeCopy to Clipboard

This exports a module definition, which requires at least a serviceCopy to Clipboard. If you named your service something other than CustomEventBusCopy to Clipboard, make sure to replace it with that.

You can learn more about what other properties you can export in your module definition in the Create a Module documentation.


Step 4: Test your Module

You can test your module in the Medusa backend by referencing it in the configurations.

To do that, add the module to the exported configuration in medusa-config.jsCopy to Clipboard as follows:

medusa-config.js
module.exports = {
// ...
modules: {
// ...
cacheService: {
resolve: "path/to/custom-module",
options: {
// any necessary options
},
},
},
}
Report Incorrect CodeCopy to Clipboard

Make sure to replace the path/to/custom-moduleCopy to Clipboard with a relative path from your Medusa backend to your module. You can learn more about module reference in the Create Module documentation.

You can also add any necessary options to the module.

Then, to test the module, run the Medusa backend which also runs your module:

npx @medusajs/medusa-cli develop
Report Incorrect CodeCopy to Clipboard

(Optional) Step 5: Publish your Module

You can publish your events module to NPM. This can be useful if you want to reuse your module across Medusa backend instances, or want to allow other developers to use it.

You can refer to the Publish Module documentation to learn how to publish your module.

Was this page helpful?