3.1.1. Guide: Implement Brand Module

In this chapter, you'll build a Brand Module that adds a brand table to the database and provides data-management features for it.

A module is a reusable package of functionalities related to a single domain or integration. Medusa comes with multiple pre-built modules for core commerce needs, such as the Cart Module that holds the data models and business logic for cart operations.

You create in a module new tables in the database, and expose a class that provides data-management methods on those tables. In the next chapters, you'll see how you use the module's functionalities to expose commerce features.

1. Create Module Directory#

Modules are created in a sub-directory of src/modules. So, start by creating the directory src/modules/brand that will hold the Brand Module's files.

2. Create Data Model#

A data model represents a table in the database. You create data models using Medusa's data modeling utility, which is built to improve readability and provide an intuitive developer experience.

You create a data model in a TypeScript or JavaScript file under the models directory of a module. So, to create a data model that represents a new brand table in the database, create the file src/modules/brand/models/brand.ts with the following content:

src/modules/brand/models/brand.ts
1import { model } from "@medusajs/framework/utils"2
3export const Brand = model.define("brand", {4  id: model.id().primaryKey(),5  name: model.text(),6})

You create a Brand data model which has an id primary key property, and a name text property.

You define the data model using the define method of the model utility imported from @medusajs/framework/utils. It accepts two parameters:

1. The first one is the name of the data model's table in the database. Use snake-case names.
2. The second is an object, which is the data model's schema.

3. Create Module Service#

You perform database operations on your data models in a service, which is a class exported by the module and acts like an interface to its functionalities.

In this step, you'll create the Brand Module's service that provides methods to manage the Brand data model. In the next chapters, you'll use this service when exposing custom features that involve managing brands.

You define a service in a service.ts or service.js file at the root of your module's directory. So, create the file src/modules/brand/service.ts with the following content:

src/modules/brand/service.ts
1import { MedusaService } from "@medusajs/framework/utils"2import { Brand } from "./models/brand"3
4class BrandModuleService extends MedusaService({5  Brand,6}) {7
8}9
10export default BrandModuleService

The BrandModuleService extends a class returned by the MedusaService function imported from @medusajs/framework/utils. This function generates a class with data-management methods for your module's data models.

The MedusaService function receives an object of the module's data models as a parameter, and generates methods to manage those data models. So, the BrandModuleService now has methods like createBrands and retrieveBrand to manage the Brand data model.

You'll use these methods in the next chapter.

4. Export Module Definition#

A module must export a definition that tells Medusa the name of the module and its main service. This definition is exported in an index.ts file at the module's root directory.

So, to export the Brand Module's definition, create the file src/modules/brand/index.ts with the following content:

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

You use the Module function imported from @medusajs/framework/utils to create the module's definition. It accepts two parameters:

1. The module's name (brand). You'll use this name when you use this module in other customizations.
2. An object with a required property service indicating the module's main service.

5. Add Module to Medusa's Configurations#

To start using your module, you must add it to Medusa's configurations in medusa-config.ts.

The object passed to defineConfig in medusa-config.ts accepts a modules property, whose value is an array of modules to add to the application. So, add the following in medusa-config.ts:

medusa-config.ts
1module.exports = defineConfig({2  // ...3  modules: [4    {5      resolve: "./src/modules/brand",6    },7  ],8})

The Brand Module is now added to your Medusa application. You'll start using it in the next chapter.

6. Generate and Run Migrations#

A migration is a TypeScript or JavaScript file that defines database changes made by a module. Migrations ensure that your module is re-usable and removes friction when working in a team, making it easy to reflect changes across team members' databases.

Medusa's CLI tool allows you to generate migration files for your module, then run those migrations to reflect the changes in the database. So, run the following commands in your Medusa application's directory:

Terminal
❯npx medusa db:generate brand❯npx medusa db:migrate

The db:generate command accepts as an argument the name of the module to generate the migrations for, and the db:migrate command runs all migrations that haven't been run yet in the Medusa application.

Next Step: Create Brand Workflow#

The Brand Module now creates a brand table in the database and provides a class to manage its records.

In the next chapter, you'll implement the functionality to create a brand in a workflow. You'll then use that workflow in a later chapter to expose an endpoint that allows admin users to create a brand.