142 lines
4.1 KiB
Plaintext
142 lines
4.1 KiB
Plaintext
export const metadata = {
|
||
title: `${pageNumber} Modules and Services`,
|
||
}
|
||
|
||
# {metadata.title}
|
||
|
||
In this chapter, you’ll learn about modules, their main service, and how to create them.
|
||
|
||
## What is a Module?
|
||
|
||
A module is a package of reusable functionalities. It can be integrated into your Medusa application without affecting the overall system.
|
||
|
||
Use modules to customize or develop commerce and architectural features in your Medusa application.
|
||
|
||
---
|
||
|
||
## How to Create a Module?
|
||
|
||
<Note title="Steps Summary">
|
||
|
||
1. Create module's main service.
|
||
2. Create module definition.
|
||
3. Add module to Medusa's configurations.
|
||
|
||
</Note>
|
||
|
||
Modules are created in a sub-directory of `src/modules`.
|
||
|
||
For example, create the directory `src/modules/hello`.
|
||
|
||
### 1. Create Main Service
|
||
|
||
A module must define a service. A service is a TypeScript or JavaScript class holding methods related to a business logic or commerce functionality.
|
||
|
||
For example, create the file `src/modules/hello/service.ts` with the following content:
|
||
|
||
```ts title="src/modules/hello/service.ts"
|
||
export default class HelloModuleService {
|
||
getMessage() {
|
||
return "Hello, world!"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. Export Module Definition
|
||
|
||
A module must have an `index.ts` file in its root directory that exports its definition. The definition specifies the main service of the module.
|
||
|
||
For example, create the file `src/modules/hello/index.ts` with the following content:
|
||
|
||
```ts title="src/modules/hello/index.ts" highlights={[["5", "", "The main service of the module."]]}
|
||
import HelloModuleService from "./service"
|
||
import { Module } from "@medusajs/utils"
|
||
|
||
export default Module("helloModuleService", {
|
||
service: HelloModuleService,
|
||
})
|
||
```
|
||
|
||
You use the `Module` function imported from `@medusajs/utils` to create the module definition. It requires two parameters:
|
||
|
||
1. The module's name.
|
||
2. An object with a required property `service` indicating the module's main service.
|
||
|
||
### 3. Add Module to Configurations
|
||
|
||
The last step is to add the module in Medusa’s configurations.
|
||
|
||
In `medusa-config.js`, add a `modules` property and pass to it your custom module:
|
||
|
||
```js title="medusa-config.js" highlights={[["4", "helloModuleService", "The key of the main service to be registered in the Medusa container."]]}
|
||
module.exports = defineConfig({
|
||
// ...
|
||
modules: {
|
||
helloModuleService: {
|
||
resolve: "./modules/hello",
|
||
},
|
||
},
|
||
})
|
||
```
|
||
|
||
Its key (`helloModuleService`) is the name of the module’s main service. It will be registered in the Medusa container with that name. It should also be the same name passed as the first parameter to the `Module` function in the module's definition.
|
||
|
||
Its value is an object having the `resolve` property, whose value is either a path to module's directory relative to `src`(it shouldn't include `src` in the path), or an `npm` package’s name.
|
||
|
||
---
|
||
|
||
## Test the Module
|
||
|
||
Since the module's main service is registered in the Medusa container, you can resolve it in other resources to use its functionalities.
|
||
|
||
For example, create the API route `src/api/store/custom/route.ts` with the following content:
|
||
|
||
```ts title="src/api/store/custom/route.ts"
|
||
import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
|
||
import HelloModuleService from "../../../modules/hello/service"
|
||
|
||
export async function GET(
|
||
req: MedusaRequest,
|
||
res: MedusaResponse
|
||
): Promise<void> {
|
||
const helloModuleService: HelloModuleService = req.scope.resolve(
|
||
"helloModuleService"
|
||
)
|
||
|
||
res.json({
|
||
message: helloModuleService.getMessage(),
|
||
})
|
||
}
|
||
```
|
||
|
||
Then, start the Medusa application:
|
||
|
||
```bash npm2yarn
|
||
npm run dev
|
||
```
|
||
|
||
Finally, send a `GET` request to `/store/custom`:
|
||
|
||
```bash apiTesting testApiUrl="http://localhost:9000/store/custom" testApiMethod="GET"
|
||
curl http://locahost:9000/store/custom
|
||
```
|
||
|
||
You’ll receive the following response:
|
||
|
||
```json
|
||
{
|
||
"message": "Hello, world!"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## When to Use Modules
|
||
|
||
<Note title="Use modules when" type="success">
|
||
|
||
- You're implementing a custom commerce feature. For example, you're implementing digital products.
|
||
- You want to re-use your custom commerce functionalities across Medusa applications or use them in other environments, such as Edge functions and Next.js apps.
|
||
|
||
</Note>
|