2.4.1. Guide: Integrate CMS Brand System

In the previous chapters, you've created a Brand Module that adds brands to your application. In this chapter, you'll integrate a dummy Content-Management System (CMS) in a new module. The module's service will provide methods to retrieve and manage brands in the CMS. You'll later use this service to sync data from and to the CMS.

1. Create Module Directory#

You'll integrate the third-party system in a new CMS Module. So, create the directory src/modules/cms that will hold the module's resources.

---

2. Create Module Service#

Next, you'll create the module's service. It will provide methods to connect and perform actions with the third-party system.

Create the CMS Module's service at src/modules/cms/service.ts with the following content:

src/modules/cms/service.ts
1import { Logger, ConfigModule } from "@medusajs/framework/types"2
3export type ModuleOptions = {4  apiKey: string5}6
7type InjectedDependencies = {8  logger: Logger9  configModule: ConfigModule10}11
12class CmsModuleService {13  private options_: ModuleOptions14  private logger_: Logger15
16  constructor({ logger }: InjectedDependencies, options: ModuleOptions) {17    this.logger_ = logger18    this.options_ = options19
20    // TODO initialize SDK21  }22}23
24export default CmsModuleService

You create a CmsModuleService that will hold the methods to connect to the third-party CMS. A service's constructor accepts two parameters:

1. The module's container. Since a module is isolated, it has a local container different than the Medusa container you use in other customizations. This container holds framework tools like the Logger utility and resources within the module.
2. Options passed to the module when it's later added in Medusa's configurations. These options are useful to pass secret keys or configurations that ensure your module is re-usable across applications. For the CMS Module, you accept the API key to connect to the dummy CMS as an option.

When integrating a third-party system that has a Node.js SDK or client, you can initialize that client in the constructor to be used in the service's methods.

Integration Methods#

Next, you'll add methods that simulate sending requests to a third-party CMS. You'll use these methods later to sync brands from and to the CMS.

Add the following methods in the CmsModuleService:

src/modules/cms/service.ts
1export class BrandClient {2  // ...3
4  // a dummy method to simulate sending a request,5  // in a realistic scenario, you'd use an SDK, fetch, or axios clients6  private async sendRequest(url: string, method: string, data?: any) {7    this.logger_.info(`Sending a ${method} request to ${url}.`)8    this.logger_.info(`Request Data: ${JSON.stringify(data, null, 2)}`)9    this.logger_.info(`API Key: ${JSON.stringify(this.options_.apiKey, null, 2)}`)10  }11
12  async createBrand(brand: Record<string, unknown>) {13    await this.sendRequest("/brands", "POST", brand)14  }15
16  async deleteBrand(id: string) {17    await this.sendRequest(`/brands/${id}`, "DELETE")18  }19
20  async retrieveBrands(): Promise<Record<string, unknown>[]> {21    await this.sendRequest("/brands", "GET")22
23    return []24  }25}

The sendRequest method sends requests to the third-party CMS. Since this guide isn't using a real CMS, it only simulates the sending by logging messages in the terminal.

You also add three methods that use the sendRequest method:

• createBrand that creates a brand in the third-party system.
• deleteBrand that deletes the brand in the third-party system.
• retrieveBrands to retrieve a brand from the third-party system.

---

3. Export Module Definition#

After creating the module's service, you'll export the module definition indicating the module's name and service.

Create the file src/modules/cms/index.ts with the following content:

src/modules/cms/index.ts
1import { Module } from "@medusajs/framework/utils"2import CmsModuleService from "./service"3
4export const CMS_MODULE = "cms"5
6export default Module(CMS_MODULE, {7  service: CmsModuleService,8})

You use Module from the Modules SDK to export the module's defintion, indicating that the module's name is cms and its service is CmsModuleService.

---

4. Add Module to Medusa's Configurations#

Finally, add the module to the Medusa configurations at medusa-config.ts:

medusa-config.ts
1module.exports = defineConfig({2  // ...3  modules: [4    // ...5    {6      resolve: "./src/modules/cms",7      options: {8        apiKey: process.env.CMS_API_KEY,9      },10    },11  ], 12})

The object passed in modules accept an options property, whose value is an object of options to pass to the module. These are the options you receive in the CmsModuleService's constructor.

You can add the CMS_API_KEY environment variable to .env:

Terminal
❯CMS_API_KEY=123

---

Next Steps: Sync Brand From Medusa to CMS#

You can now use the CMS Module's service to perform actions on the third-party CMS.

In the next chapter, you'll learn how to emit an event when a brand is created, then handle that event to sync the brand from Medusa to the third-party service.

Edit this page