asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: revise events and subscribers (#10227)

Browse Source
This commit is contained in:
Shahed Nasser
2024-11-22 14:39:29 +02:00
committed by GitHub
parent 4810b1c55b
commit b558800547
2 changed files with 63 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
www/apps/book/app/learn/basics/events-and-subscribers/page.mdx
View File

@@ -4,46 +4,77 @@ export const metadata = {
# {metadata.title}
In this chapter, you’ll learn how to handle events with subscribers.
In this chapter, you’ll learn about Medusa's event system, and how to handle events with subscribers.
## What is an Event?
## Handle Core Commerce Flows with Events
When an action is performed in Medusa, such as creating a product, the Medusa application emits an event.
When building commerce digital applications, you'll often need to perform an action after a commerce operation is performed. For example, sending an order confirmation email when the customer places an order.
You can listen to those events and perform an asynchronous action using a subscriber.
In other commerce platforms, it can be tricky to implement this when the commerce operation is performed in the platform's core. You resort to hacky workarounds or extend core services to perform your custom action, which becomes difficult to maintain in the long run and as your application grows.
Medusa's event system removes this complexity by emitting events when core commerce features are performed. Your efforts only go into handling these events in subscribers, which are functions executed asynchronously when an event is emitted.
![A diagram showcasing an example of how an event is emitted when an order is placed.](https://res.cloudinary.com/dza7lstvk/image/upload/v1732277948/Medusa%20Book/order-placed-event-example_e4e4kw.jpg)
Subscribers are useful to perform actions that aren't integral to the original flow. For example, you can handle the `order.placed` event in a subscriber that sends a confirmation email to the customer. The subscriber has no impact on the original order-placement flow, as it's executed outside of it.
<Note>
If the action you're performing is integral to the main flow of the core commerce feature, use [workflow hooks](../../advanced-development/workflows/workflow-hooks/page.mdx) instead.
</Note>
### List of Emitted Events
Find a list of all emitted events in [this reference](!resources!/events-reference).
---
## What is a Subscriber?
## How to Create a Subscriber?
A subscriber is a function executed whenever the event it listens to is emitted.
You create a subscriber in a TypeScript or JavaScript file under the `src/subscribers` directory. The file exports the function to execute and the subscriber's configuration that indicate what event(s) it listens to.
### How to Create a Subscriber?
A subscriber is created in a TypeScript or JavaScript file under the `src/subscribers` directory.
For example, create the file `src/subscribers/product-created.ts` with the following content:
For example, create the file `src/subscribers/order-placed.ts` with the following content:
```ts title="src/subscribers/product-created.ts"
import { type SubscriberConfig } from "@medusajs/framework"
import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
import { sendOrderConfirmationWorkflow } from "../workflows/send-order-confirmation"
// subscriber function
export default async function productCreateHandler() {
console.log("A product was created")
export default async function orderPlacedHandler({
event: { data },
container,
}: SubscriberArgs<{ id: string }>) {
const logger = container.resolve(
ContainerRegistrationKeys.LOGGER
)
logger.info("Sending confirmation email...")
await sendOrderConfirmationWorkflow(container)
.run({
input: {
id: data.id
}
})
}
// subscriber config
export const config: SubscriberConfig = {
event: "product.created",
event: `order.placed`,
}
```
A subscriber file must export:
This subscriber file exports:
- An asynchronous subscriber function that's executed whenever the associated event is triggered.
- A configuration object defining the event this subscriber is listening to.
- An asynchronous subscriber function that's executed whenever the associated event, which is `order.placed` is triggered.
- A configuration object with an `event` property whose value is the event the subscriber is listening to. You can also pass an array of event names to listen to multiple events in the same subscriber.
The above subscriber listens to the `product.created` event. Whenever the event is emitted, it logs in the terminal `A product is created`.
The subscriber function receives an object as a parameter that has the following properties:
- `event`: An object with the event's details. The `data` property contains the data payload of the event emitted, which is the order's ID in this case.
- `container`: The [Medusa container](../medusa-container/page.mdx) that you can use to resolve registered resources.
In the subscriber function, you use the container to resolve the Logger utility and log a message in the console. Also, assuming you have a [workflow](../workflows/page.mdx) that sends an order confirmation email, you execute it in the subscriber.
---
@@ -55,69 +86,24 @@ To test the subscriber, start the Medusa application:
npm run dev
```
Then, go to the Medusa Admin at `localhost:9000/app` and create a product. You’ll see the following messages logged in the Medusa application's terminal:
Then, try placing an order either using Medusa's API routes or the [Next.js Storefront](../../storefront-development/nextjs-starter/page.mdx). You'll see the following message in the terminal:
```bash
info: Processing product.created which has 1 subscribers
A product was created
info: Processing order.placed which has 1 subscribers
Sending confirmation email...
```
The first message indicates that the `product.created` event was emitted, and the second one is the message logged from the subscriber.
The first message indicates that the `order.placed` event was emitted, and the second one is the message logged from the subscriber.
---
## When to Use Subscribers
## Event Module
<Note title="Use subscribers when" type="success">
The subscription and emitting of events is handled by an Event Module, an architectural module that implements the pub/sub functionalities of Medusa's event system.
You want to perform an action everytime a specific event is emitted in the Medusa application.
Medusa provides two Event Modules out of the box:
</Note>
- [Local Event Module](!resources!/architectural-modules/event/local), used by default. It's useful for development, as you don't need additional setup to use it.
- [Redis Event Module](!resources!/architectural-modules/event/redis), which is useful in production. It uses [Redis](https://redis.io/) to implement Medusa's pub/sub events system.
---
## Resolve Resources
The subscriber function accepts an object parameter with the property `container`. Its value is the Medusa container, and you can use it to resolve other resources, such as services.
For example:
export const highlights = [
["7", "container", "Recieve the Medusa Container in the object parameter."],
["10", "resolve", "Resolve the Product Module's main service."],
["10", "Modules.PRODUCT", "The module's registration name imported from `@medusajs/framework/utils`."]
]
```ts title="src/subscribers/product-created.ts" highlights={highlights}
import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
import { IProductModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
export default async function productCreateHandler({
event: { data },
container,
}: SubscriberArgs<{ id: string }>) {
const productModuleService: IProductModuleService =
container.resolve(Modules.PRODUCT)
const productId = data.id
const product = await productModuleService.retrieveProduct(
productId
)
console.log(`The product ${product.title} was created`)
}
export const config: SubscriberConfig = {
event: `product.created`,
}
```
You use the container to resolve the Product Module's main service, then log the title of the created product.
---
## Events List
Find a list of all emitted events in [this reference](!resources!/events-reference).
Medusa's [architecture](../../advanced-development/architecture/overview/page.mdx) also allows you to build a custom Event Module that uses a different service or logic to implement the pub/sub system. Learn how to build an Event Module in [this guide](!resources!/architectural-modules/event/create).

2
www/apps/book/generated/edit-dates.mjs
View File

@@ -23,7 +23,7 @@ export const generatedEditDates = {
"app/learn/basics/api-routes/page.mdx": "2024-09-11T10:48:31.777Z",
"app/learn/basics/modules-directory-structure/page.mdx": "2024-10-03T13:03:35.957Z",
"app/learn/advanced-development/workflows/access-workflow-errors/page.mdx": "2024-09-18T12:54:04.695Z",
"app/learn/basics/events-and-subscribers/page.mdx": "2024-09-30T08:43:53.131Z",
"app/learn/basics/events-and-subscribers/page.mdx": "2024-11-22T12:19:32.916Z",
"app/learn/advanced-development/modules/container/page.mdx": "2024-11-21T08:59:18.707Z",
"app/learn/advanced-development/workflows/execute-another-workflow/page.mdx": "2024-09-30T08:43:53.129Z",
"app/learn/basics/loaders/page.mdx": "2024-11-22T10:51:32.931Z",