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.ts
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>
where <service_name>
is the name of the service you’re integrating. For example, event-bus-redis
.
Add the following content to the file:
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
This creates the class CustomEventBus
that implements the AbstractEventBusModuleService
class imported from @medusajs/utils
. Feel free to rename the class to what’s relevant for your event bus service.
In the class you must implement the emit
method. You can optionally implement the subscribe
and unsubscribe
methods.
Step 2: Implement Methods
Note About the eventToSubscribersMap Property
The AbstractEventBusModuleService
implements two methods for handling subscription: subscribe
and unsubscribe
. In these methods, the subscribed handler functions are managed within a class property eventToSubscribersMap
, which is a JavaScript Map. The map's keys are the event names, whereas the value of each key is an array of subscribed handler functions.
In your custom implementation, you can use this property to manage the subscribed handler functions. For example, you can get the subscribers of a method using the get
method of the map:
Alternatively, you can implement custom logic for the subscribe
and unsubscribe
events, which is explained later in this guide.
constructor
The constructor
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.js
, and to other services and resources in the Medusa backend using dependency injection.
Here’s an example of how you can use the constructor
to store the options of your module:
emit
The emit
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 emit
method has two different signatures:
- The first signature accepts three parameters. The first parameter is
eventName
being a required string indicating the name of the event to trigger. The second parameter isdata
being the optional data to send to subscribers of that event. The third optional parameteroptions
which can be used to pass options specific to the event bus. - The second signature accepts one parameter, which is an array of objects having three properties:
eventName
,data
, andoptions
. These are the same as the parameters that can be passed in the first signature. This signature allows emitting more than one event.
The options
parameter depends on the event bus integration. For example, the Redis event bus accepts the following options:
You can implement your method in a way that supports both signatures by checking the type of the first input. For example:
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
}
}
(optional) subscribe
As mentioned earlier, this method is already implemented in the AbstractEventBusModuleService
class. This section explains how you can implement your custom subscribe logic if necessary.
The subscribe
method attaches a handler function to the specified event, which is run when the event is triggered. It is typically used inside a subscriber class.
The subscribe
method accepts three parameters:
- The first parameter
eventName
is a required string. It indicates which event the handler function is subscribing to. - The second parameter
subscriber
is a required function that performs an action when the event is triggered. - The third parameter
context
is an optional object that has the propertysubscriberId
. Subscriber IDs are useful to differentiate between handler functions 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 thesubscribe
method.
The implementation of this method depends on the service you’re using for the event bus:
(optional) unsubscribe
As mentioned earlier, this method is already implemented in the AbstractEventBusModuleService
class. This section explains how you can implement your custom unsubscribe logic if necessary.
The unsubscribe
method is used to unsubscribe a handler function from an event.
The unsubscribe
method accepts three parameters:
- The first parameter
eventName
is a required string. It indicates which event the handler function is unsubscribing from. - The second parameter
subscriber
is a required function that was initially subscribed to the event. - The third parameter
context
is an optional object that has the propertysubscriberId
. 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:
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.ts
with the following content:
This exports a module definition, which requires at least a service
. If you named your service something other than CustomEventBus
, 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.js
as follows:
Make sure to replace the path/to/custom-module
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:
(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.