docs: fixes and changes based on latest updates (#7322)
* docs: changes based on DX changes * remove fields no longer needed * remove unnecessary parameters * fixes to authenticate middleware usage * add highlight to migrations config * change configuration to http * added missing remote link docs * fix name in sidebar * added notification module docs + updated file module docs * add vale exceptions * fix vale errors * added docs on custom cli scripts
This commit is contained in:
Shahed Nasser
+17
-1
@@ -6,6 +6,22 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
Learn how to create a cache module in [this guide](./create/page.mdx).
|
||||
A Cache Module is used to cache the results of computations such as price selection or various tax calculations.
|
||||
|
||||
The underlying database, third-party service, or caching logic is flexible since it's implemented in a module. You can choose from Medusa’s cache modules or create your own to support something more suitable for your architecture.
|
||||
|
||||
---
|
||||
|
||||
## List of Cache Modules
|
||||
|
||||
By default, Medusa uses the In-Memory Cache Module. This module uses a plain JavaScript Map object to store the cache data.
|
||||
|
||||
This is useful for development. However, for production, it's highly recommended to use other Cache Modules, such as the Redis Cache Module.
|
||||
|
||||
<ChildDocs type="item" filters={["Guides"]} onlyTopLevel={true} />
|
||||
|
||||
---
|
||||
|
||||
## Create a Cache Module
|
||||
|
||||
To create a cache module, refer to [this guide](./create/page.mdx).
|
||||
|
||||
@@ -6,6 +6,22 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
Learn how to create a event module in [this guide](./create/page.mdx).
|
||||
An Event Module implements the underlying publish/subscribe system that handles queueing events, emitting them, and executing their subscribers.
|
||||
|
||||
This makes the event architecture customizable, as you can either choose one of Medusa’s event modules or create your own.
|
||||
|
||||
---
|
||||
|
||||
## List of Event Modules
|
||||
|
||||
By default, Medusa uses the Local Event Module. This module uses Node’s EventEmitter to implement the publish/subscribe system.
|
||||
|
||||
This is useful for development. However, for production, it’s highly recommended to use other Event Modules, Redis Event Module.
|
||||
|
||||
<ChildDocs type="item" filters={["Guides"]} onlyTopLevel={true} />
|
||||
|
||||
---
|
||||
|
||||
## Create a Event Module
|
||||
|
||||
To create an event module, refer to [this guide](./create/page.mdx).
|
||||
|
||||
@@ -6,6 +6,22 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
Learn how to create a file provider module in [this guide](/references/file-provider-module).
|
||||
A File Module exposes the functionalities to upload assets, such as product images, to the Medusa application.
|
||||
|
||||
---
|
||||
|
||||
## What is a File Provider Module?
|
||||
|
||||
A file provider module implements the logic of handling uploads and downloads. The File Module must have one file provider module configured.
|
||||
|
||||
By default, Medusa uses the Local File Module. This module uploads files to the `uploads` directory of your Medusa application.
|
||||
|
||||
This is useful for development. However, for production, it’s highly recommended to use other File Modules, such as the S3 Module.
|
||||
|
||||
<ChildDocs type="item" filters={["Guides"]} onlyTopLevel={true} />
|
||||
|
||||
---
|
||||
|
||||
## Create a File Provider Module
|
||||
|
||||
To create a file provider module, refer to [this guide](/references/file-provider-module).
|
||||
|
||||
@@ -0,0 +1,311 @@
|
||||
import { Table, Tabs, TabsList, TabsContent, TabsContentWrapper, TabsTrigger } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `S3 File Provider Module`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
The S3 File Provider Module integrates Amazon S3 and services following a compatible API (such as MinIO or DigitalOcean Spaces) to store files uploaded to your Medusa application.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
<Tabs defaultValue="aws">
|
||||
<TabsList>
|
||||
<TabsTrigger value="aws">AWS S3</TabsTrigger>
|
||||
<TabsTrigger value="minio">MinIO</TabsTrigger>
|
||||
<TabsTrigger value="spaces">DigitalOcean Spaces</TabsTrigger>
|
||||
</TabsList>
|
||||
<TabsContentWrapper>
|
||||
<TabsContent value="aws">
|
||||
|
||||
- [AWS account](https://console.aws.amazon.com/console/home?nc2=h_ct&src=header-signin).
|
||||
- [S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) with the "Public Access setting" enabled.
|
||||
- [AWS user with AmazonS3FullAccess permissions](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-create-and-attach-iam-policy.html).
|
||||
- [AWS user access key ID and secret access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey).
|
||||
- Change your [bucket's policy](https://docs.aws.amazon.com/AmazonS3/latest/userguide/add-bucket-policy.html) to the following:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Id": "Policy1397632521960",
|
||||
"Statement": [
|
||||
{
|
||||
"Sid": "Stmt1397633323327",
|
||||
"Effect": "Allow",
|
||||
"Principal": {
|
||||
"AWS": "*"
|
||||
},
|
||||
"Action": "s3:GetObject",
|
||||
"Resource": "arn:aws:s3:::{bucket_name}/*"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Make sure to replace `{bucket_name}` with the name of the bucket you created.
|
||||
|
||||
</TabsContent>
|
||||
<TabsContent value="minio">
|
||||
|
||||
- [Install MinIO](https://min.io/docs/minio/linux/index.html).
|
||||
- Change port to `9001` using the [console address](https://min.io/docs/minio/linux/reference/minio-server/minio-server.html#minio.server.-console-address) and [address](https://min.io/docs/minio/linux/reference/minio-server/minio-server.html#minio.server.-address) CLI options.
|
||||
- [MinIO bucket with public access policy](https://min.io/docs/minio/linux/administration/console/managing-objects.html#creating-buckets).
|
||||
- [MinIO access and secret access key](https://min.io/docs/minio/linux/administration/console/security-and-access.html#id1).
|
||||
|
||||
</TabsContent>
|
||||
<TabsContent value="spaces">
|
||||
|
||||
- [DigitalOcean account](https://cloud.digitalocean.com/registrations/new).
|
||||
- [DigitalOcean Spaces bucket](https://docs.digitalocean.com/products/spaces/how-to/create/).
|
||||
- [DigitalOcean Spaces access and secret access keys](https://docs.digitalocean.com/products/spaces/how-to/manage-access/#access-keys).
|
||||
|
||||
</TabsContent>
|
||||
</TabsContentWrapper>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## Install the S3 File Module
|
||||
|
||||
To install the S3 File Provider Module, run the following command in the directory of your Medusa application:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/file-s3
|
||||
```
|
||||
|
||||
Next, add the module into the `providers` array of the File Module:
|
||||
|
||||
<Note>
|
||||
|
||||
The File Module accepts one provider only.
|
||||
|
||||
</Note>
|
||||
|
||||
```js title="medusa-config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
modules: {
|
||||
// ...
|
||||
[Modules.FILE]: {
|
||||
resolve: "@medusajs/file",
|
||||
options: {
|
||||
providers: [
|
||||
{
|
||||
resolve: "@medusajs/file-s3",
|
||||
options: {
|
||||
config: {
|
||||
s3: {
|
||||
file_url: process.env.S3_FILE_URL,
|
||||
access_key_id: process.env.S3_ACCESS_KEY_ID,
|
||||
secret_access_key: process.env.S3_SECRET_ACCESS_KEY,
|
||||
region: process.env.S3_REGION,
|
||||
bucket: process.env.S3_BUCKET,
|
||||
endpoint: process.env.S3_ENDPOINT,
|
||||
// other options...
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### S3 File Module Options
|
||||
|
||||
<Table>
|
||||
<Table.Header>
|
||||
<Table.Row>
|
||||
<Table.HeaderCell>Option</Table.HeaderCell>
|
||||
<Table.HeaderCell>Description</Table.HeaderCell>
|
||||
<Table.HeaderCell>Default</Table.HeaderCell>
|
||||
</Table.Row>
|
||||
</Table.Header>
|
||||
<Table.Body>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`file_url`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
The base URL to upload files to.
|
||||
|
||||
- For AWS S3, the endpoint is of the format `https://{bucket}.s3.{region}.amazonaws.com`
|
||||
- For MinIO, it's the URL to the MinIO server.
|
||||
- For DigitalOcean Spaces, it's either the Origin Endpoint or the CDN endpoint of your Spaces Object Storage bucket.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
\-
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`access_key_id`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
The AWS or (S3 compatible) user's access key ID.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
\-
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`secret_access_key`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
The AWS or (S3 compatible) user's secret access key.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
\-
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`region`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
The bucket's region code.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
\-
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`bucket`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
The bucket's name.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
\-
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`endpoint`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
The URL to the AWS S3 (or compatible S3 API) server.
|
||||
|
||||
- For AWS S3, the endpoint is of the format `{bucket}.s3.{region}.amazonaws.com`
|
||||
- For MinIO, it's the URL to the MinIO server.
|
||||
- For DigitalOcean Spaces, it's the Spaces Origin Endpoint.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
\-
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`prefix`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
A string to prefix each uploaded file's name.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
\-
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`cache_control`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
A string indicating how long objects remain in the AWS S3 (or compatible S3 API) cache.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
`public, max-age=31536000`
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`download_file_duration`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
A number indicating the expiry time of presigned URLs in seconds.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
`3600` (An hour)
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`additional_client_config`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
Any additional configurations to pass to the S3 client.
|
||||
|
||||
Refer to [this AWS API reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html) for a full list of accepted configuration.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
\-
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
</Table.Body>
|
||||
</Table>
|
||||
@@ -0,0 +1,80 @@
|
||||
import { Table } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Local Notification Provider Module`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
The Local Notification Provider Module simulates sending a notification, but only logs the notification's details in the terminal. This is useful for development.
|
||||
|
||||
---
|
||||
|
||||
## Install the Local Notification Module
|
||||
|
||||
To install the Local Notification Provider Module, run the following command in the directory of your Medusa application:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/notification-local
|
||||
```
|
||||
|
||||
Next, add the module into the `providers` array of the Notification Module:
|
||||
|
||||
<Note>
|
||||
|
||||
Only one provider can be defined for a channel.
|
||||
|
||||
</Note>
|
||||
|
||||
```js title="medusa-config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
modules: {
|
||||
// ...
|
||||
[Modules.NOTIFICATION]: {
|
||||
resolve: "@medusajs/notification",
|
||||
options: {
|
||||
providers: [
|
||||
// ...
|
||||
{
|
||||
resolve: "@medusajs/notification-local",
|
||||
options: {
|
||||
config: {
|
||||
local: {
|
||||
channels: ["email"]
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Local Notification Module Options
|
||||
|
||||
<Table>
|
||||
<Table.Header>
|
||||
<Table.Row>
|
||||
<Table.HeaderCell>Option</Table.HeaderCell>
|
||||
<Table.HeaderCell>Description</Table.HeaderCell>
|
||||
</Table.Row>
|
||||
</Table.Header>
|
||||
<Table.Body>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`channels`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
The channels this notification module is used to send notifications for. While the local notification module doesn't actually send the notification,
|
||||
it's important to specify its channels to make sure it's used when a notification for that channel is created.
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
</Table.Body>
|
||||
</Table>
|
||||
@@ -0,0 +1,66 @@
|
||||
import { ChildDocs } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Notification Provider Modules`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
A Notification Module exposes the functionalities to send a notification to a customer or user. For example, sending an order confirmation email.
|
||||
|
||||
You can resolve the Notification Module and send notifications in API routes, subscribers, or other resources.
|
||||
|
||||
---
|
||||
|
||||
## What is a Notification Provider Module?
|
||||
|
||||
A notification provider module implements the logic of sending the notification. It either integrates a third-party service or uses custom logic to send the notification.
|
||||
|
||||
By default, Medusa uses the Local Notification Module which only simulates sending the notification by logging a message in the terminal.
|
||||
|
||||
Medusa provides other Notification Modules that actually send notifications, such as the SendGrid Notification Provider Module.
|
||||
|
||||
<ChildDocs type="item" filters={["Guides"]} onlyTopLevel={true} />
|
||||
|
||||
---
|
||||
|
||||
## Notification Provider Module Channels
|
||||
|
||||
When you send a notification, you specify the channel to send it through, such as `email` or `sms`. Each provider defined in the Notification Module's `providers` option has a `channels` option specifying which channels it can be used in. Only one provider can be setup for each channel.
|
||||
|
||||
For example:
|
||||
|
||||
```js title="medusa-config.js" highlights={[["15"]]}
|
||||
module.exports = {
|
||||
// ...
|
||||
modules: {
|
||||
// ...
|
||||
[Modules.NOTIFICATION]: {
|
||||
resolve: "@medusajs/notification",
|
||||
options: {
|
||||
providers: [
|
||||
// ...
|
||||
{
|
||||
resolve: "@medusajs/notification-local",
|
||||
options: {
|
||||
config: {
|
||||
local: {
|
||||
channels: ["email"]
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
The `channels` option is an array of strings indicating the channels this provider is used for.
|
||||
|
||||
---
|
||||
|
||||
## Create a Notification Provider Module
|
||||
|
||||
To create a notification provider module, refer to [this guide](/references/notification-provider-module).
|
||||
@@ -0,0 +1,86 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Send Notification with the Notification Module`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this guide, you'll learn how to send a notification using the Notification Module.
|
||||
|
||||
## Use the Create Method
|
||||
|
||||
In your resource, such as a subscriber, resolve the Notification Module's main service and use its `create` method:
|
||||
|
||||
export const highlights = [
|
||||
["12", "notificationModuleService", "Resolve the Notification Module."],
|
||||
["17", "create", "Create the notification to be sent."],
|
||||
["19", '"email"', "Use the provider module defined for the `email` channel to send an email."],
|
||||
["20", '"product-created"', "The ID of the template defined in the third-party service, such as SendGrid."],
|
||||
["21", "data", "The data to pass to the template defined in the third-party service."]
|
||||
]
|
||||
|
||||
```ts title="src/subscribers/product-created.ts" highlights={highlights}
|
||||
import type {
|
||||
SubscriberArgs,
|
||||
SubscriberConfig,
|
||||
} from "@medusajs/medusa"
|
||||
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
|
||||
import { INotificationModuleService } from "@medusajs/types"
|
||||
|
||||
export default async function productCreateHandler({
|
||||
data,
|
||||
container
|
||||
}: SubscriberArgs<{ id: string }>) {
|
||||
const notificationModuleService: INotificationModuleService =
|
||||
container.resolve(
|
||||
ModuleRegistrationName.NOTIFICATION
|
||||
)
|
||||
|
||||
await notificationModuleService.create({
|
||||
to: "shahednasser@gmail.com",
|
||||
channel: "email",
|
||||
template: "product-created",
|
||||
data: "data" in data ? data.data : data
|
||||
})
|
||||
}
|
||||
|
||||
export const config: SubscriberConfig = {
|
||||
event: "product.created",
|
||||
}
|
||||
```
|
||||
|
||||
The `create` method accepts an object or an array of objects having the following properties:
|
||||
|
||||
<TypeList
|
||||
types={[
|
||||
{
|
||||
name: "to",
|
||||
type: "`string`",
|
||||
description: "The destination to send the notification to. When sending an email, it'll be the email address. When sending an SMS, it'll be the phone number.",
|
||||
optional: false,
|
||||
},
|
||||
{
|
||||
name: "channel",
|
||||
type: "`string`",
|
||||
description: "The channel to send the notification through. For example, `email` or `sms`. The provider module defined for that channel will be used to send the notification.",
|
||||
optional: false
|
||||
},
|
||||
{
|
||||
name: "template",
|
||||
type: "`string`",
|
||||
description: "The ID of the template used for the notification. This is useful for providers like SendGrid, where you define templates within SendGrid and use their IDs here.",
|
||||
optional: false
|
||||
},
|
||||
{
|
||||
name: "data",
|
||||
type: "`Record<string, unknown>`",
|
||||
description: "The data to pass along to the template, if necessary."
|
||||
}
|
||||
]}
|
||||
sectionTitle="Use the Create Method"
|
||||
/>
|
||||
|
||||
{/* TODO add once reference for type once generated */}
|
||||
|
||||
{/* For a full list of properties accepted, refer to [this guide](/references/notification-provider-module#create). */}
|
||||
@@ -0,0 +1,192 @@
|
||||
import { Table } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `SendGrid Notification Provider Module`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
The SendGrid Notification Provider Module integrates [SendGrid](https://sendgrid.com) to send emails to users and customers.
|
||||
|
||||
---
|
||||
|
||||
## Install the SendGrid Notification Module
|
||||
|
||||
<Note type="check">
|
||||
|
||||
- [SendGrid account](https://signup.sendgrid.com)
|
||||
- [Setup SendGrid single sender](https://docs.sendgrid.com/ui/sending-email/sender-verification)
|
||||
- [SendGrid API Key](https://docs.sendgrid.com/ui/account-and-settings/api-keys)
|
||||
|
||||
</Note>
|
||||
|
||||
To install the SendGrid Notification Provider Module, run the following command in the directory of your Medusa application:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/notification-sendgrid
|
||||
```
|
||||
|
||||
Next, add the module into the `providers` array of the Notification Module:
|
||||
|
||||
<Note>
|
||||
|
||||
Only one provider can be defined for a channel.
|
||||
|
||||
</Note>
|
||||
|
||||
```js title="medusa-config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
modules: {
|
||||
// ...
|
||||
[Modules.NOTIFICATION]: {
|
||||
resolve: "@medusajs/notification",
|
||||
options: {
|
||||
providers: [
|
||||
// ...
|
||||
{
|
||||
resolve: "@medusajs/notification-sendgrid",
|
||||
options: {
|
||||
config: {
|
||||
sendgrid: {
|
||||
channels: ["email"],
|
||||
api_key: process.env.SENDGRID_API_KEY,
|
||||
from: process.env.SENDGRID_FROM
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Make sure to add the following environment variables:
|
||||
|
||||
```bash
|
||||
SENDGRID_API_KEY=<YOUR_SENDGRID_API_KEY>
|
||||
SENDGRID_FROM=<YOUR_SENDGRID_FROM>
|
||||
```
|
||||
|
||||
### SendGrid Notification Module Options
|
||||
|
||||
<Table>
|
||||
<Table.Header>
|
||||
<Table.Row>
|
||||
<Table.HeaderCell>Option</Table.HeaderCell>
|
||||
<Table.HeaderCell>Description</Table.HeaderCell>
|
||||
</Table.Row>
|
||||
</Table.Header>
|
||||
<Table.Body>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`channels`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
The channels this notification module is used to send notifications for. Only one provider can be defined for a channel.
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`api_key`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
The SendGrid API key.
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`from`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
The SendGrid from email.
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
</Table.Body>
|
||||
</Table>
|
||||
|
||||
---
|
||||
|
||||
## SendGrid Templates
|
||||
|
||||
When you send a notification, you must specify the ID of the template to use in SendGrid.
|
||||
|
||||
Refer to [this SendGrid documentation guide](https://docs.sendgrid.com/ui/sending-email/how-to-send-an-email-with-dynamic-templates) on how to create templates for your different email types.
|
||||
|
||||
---
|
||||
|
||||
## Test out the Module
|
||||
|
||||
To test the module out, create a simple subscriber at `src/subscribers/product-created.ts` with the following content:
|
||||
|
||||
export const highlights = [
|
||||
["12", "notificationModuleService", "Resolve the Notification Module."],
|
||||
["17", "create", "Create the notification to be sent."],
|
||||
["19", '"email"', "By specifying the `email` channel, SendGrid will be used to send the notification."],
|
||||
["20", '"product-created"', "The ID of the template defined in SendGrid."],
|
||||
["21", "data", "The data to pass to the template defined in SendGrid."]
|
||||
]
|
||||
|
||||
```ts title="src/subscribers/product-created.ts" highlights={highlights}
|
||||
import type {
|
||||
SubscriberArgs,
|
||||
SubscriberConfig,
|
||||
} from "@medusajs/medusa"
|
||||
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
|
||||
import { INotificationModuleService } from "@medusajs/types"
|
||||
|
||||
export default async function productCreateHandler({
|
||||
data,
|
||||
container
|
||||
}: SubscriberArgs<{ id: string }>) {
|
||||
const notificationModuleService: INotificationModuleService =
|
||||
container.resolve(
|
||||
ModuleRegistrationName.NOTIFICATION
|
||||
)
|
||||
|
||||
await notificationModuleService.create({
|
||||
to: "test@gmail.com",
|
||||
channel: "email",
|
||||
template: "product-created",
|
||||
data: "data" in data ? data.data : data
|
||||
})
|
||||
}
|
||||
|
||||
export const config: SubscriberConfig = {
|
||||
event: "product.created",
|
||||
}
|
||||
```
|
||||
|
||||
In this subscriber:
|
||||
|
||||
- Resolve the Notification Module's main service.
|
||||
- Use the `create` method of the main service to create a notification to be sent to the specified email.
|
||||
- By specifying the `email` channel, the SendGrid Notification Provider Module is used to send the notification.
|
||||
- The `template` property of the `create` method's parameter specifies the ID of the template defined in SendGrid.
|
||||
- The `data` property allows you to pass data to the template in SendGrid.
|
||||
|
||||
Then, start the Medusa application:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run dev
|
||||
```
|
||||
|
||||
{/* TODO add links */}
|
||||
|
||||
And create a product either using the [API route](!api!/api/admin#products_postproducts) or the Medusa Admin. This runs the subscriber and sends an email using SendGrid.
|
||||
@@ -0,0 +1,13 @@
|
||||
import { ChildDocs } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Workflow Engine Modules`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
Workflow engine modules handle tracking and recording the transactions and statuses of workflows and their steps.
|
||||
|
||||
Medusa uses the In-Memory Workflow Engine Module by default. For production purposes, it's recommended to use the Redis Engine Module instead.
|
||||
|
||||
<ChildDocs type="item" filters={["Guides"]} onlyTopLevel={true} />
|
||||
Reference in New Issue
Block a user