In this document, you’ll learn what events are and why they’re useful in Medusa.
Events are used in Medusa to inform different parts of the commerce ecosystem that this event occurred. For example, when an order is placed, the
order.placed event is triggered, which informs notification services like SendGrid to send a confirmation email to the customer.
The events system in Medusa is built on a publish/subscribe architecture. The Medusa core publish an event when an action takes place, and modules, plugins, or other forms of customizations can subscribe to that event. Subscribers can then perform a task asynchronously when the event is triggered.
Although the core implements the main logic behind the events system, you’ll need to use an event module that takes care of the publish/subscribe functionality such as subscribing and emitting events. Medusa provides modules that you can use both for development and production, including Redis and Local modules.
Transactions in Medusa ensure Atomicity, Consistency, Isolation, and Durability (ACID) guarantees for operations in the Medusa core.
In many cases, services typically update resources in the database and emit an event within a transactional operation. To ensure that these events don't cause data inconsistencies (for example, a plugin subscribes to an event to contact a third-party service, but the transaction fails) the concept of a staged job is introduced.
Instead of events being processed immediately, they're stored in the database as a staged job until they're ready. In other words, until the transaction has succeeded.
This rather complex logic is abstracted away from the consumers of the EventBusService, but here's an example of the flow when an API request is made:
- API request starts.
- Transaction is initiated.
- Service layer performs some logic.
- Events are emitted and stored in the database for eventual processing.
- Transaction is committed.
- API request ends.
- Events in the database become visible.
To pull staged jobs from the database, a separate enqueuer polls the database every three seconds to discover new visible jobs. These jobs are then added to the queue and processed as described in the Processing section earlier.
You can emit events in Medusa using the
EventBusService. For example:
You can also emit more than one event:
Medusa’s default starter project comes with the local event module (
@medusajs/event-bus-local). For production environments, it’s recommended to use the Redis event module package (
@medusajs/event-bus-redis) that you can install.
Learn how to install Redis events module in Medusa.
Learn how to install local events module in Medusa.
Developers can create custom event modules, allowing them to integrate any third-party services or logic to handle this functionality. Developers can also create and use subscribers to handle events in Medusa.
Learn how to create an event module.
Learn how to create a subscriber.