diff --git a/www/apps/book/app/learn/customization/custom-features/module/page.mdx b/www/apps/book/app/learn/customization/custom-features/module/page.mdx index eacdc739fd..8d02aee745 100644 --- a/www/apps/book/app/learn/customization/custom-features/module/page.mdx +++ b/www/apps/book/app/learn/customization/custom-features/module/page.mdx @@ -1,24 +1,38 @@ export const metadata = { - title: `${pageNumber} Implement Brand Module`, + title: `${pageNumber} Guide: Implement Brand Module`, } # {metadata.title} - +In this chapter, you'll build a Brand Module that adds a `brand` table to the database and provides data-management features for it. -This chapter covers how to create a Brand Module as part of the ["Build Custom Features" chapter](../page.mdx). +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](!resources!/commerce-modules/cart) 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. + + + +Learn more about modules in [this chapter](../../../basics/modules/page.mdx). ## 1. Create Module Directory -Start by creating the directory `src/modules/brand` that will hold the Brand Module's files. +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 -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: +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. + + + +Learn more about data models in [this chapter](../../../basics/modules/page.mdx#1-create-data-model). + + + +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: ```ts title="src/modules/brand/models/brand.ts" import { model } from "@medusajs/framework/utils" @@ -29,15 +43,34 @@ export const Brand = model.define("brand", { }) ``` -This creates a `Brand` data model which has an `id` primary key property, and a `name` text property. +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. + + + +Learn about other property types in [this chapter](../../../advanced-development/data-models/property-types/page.mdx). + + --- ## 3. Create Module Service -Next, you'll create the module's main service that manages the `Brand` data model. +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. -Create the file `src/modules/brand/service.ts` with the following content: +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. + + + +Learn more about services in [this chapter](../../../basics/modules/page.mdx#2-create-service). + + + +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: export const serviceHighlights = [ ["4", "MedusaService", "A service factory that generates data-management methods."] @@ -56,48 +89,55 @@ class BrandModuleService extends MedusaService({ export default BrandModuleService ``` -The `BrandModuleService` extends a `MedusaService` function imported from `@medusajs/framework/utils` which is a service factory. +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, such as `createBrands` and `updateBrands`. +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. -Those methods are now available at the `BrandModuleService` class and you'll use them in upcoming steps. +You'll use these methods in the [next chapter](../workflow/page.mdx). -Find a reference of the generated methods in [this guide](!resources!/service-factory-reference). +Find a reference of all generated methods in [this guide](!resources!/service-factory-reference). --- -## 4. Create Module's Definition +## 4. Export Module Definition -To export the module's definition, create the file `src/modules/brand/index.ts` with the following content: +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: ```ts title="src/modules/brand/index.ts" import { Module } from "@medusajs/framework/utils" import BrandModuleService from "./service" -export const BRAND_MODULE = "brandModuleService" +export const BRAND_MODULE = "brand" export default Module(BRAND_MODULE, { service: BrandModuleService, }) ``` -This exposes the module to your application and allows you to resolve the `BrandModuleService`, which is its main service. +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. -Learn more about modules and services [in this guide](../../../basics/modules/page.mdx). + + +You export `BRAND_MODULE` to reference the module's name more reliably in other customizations. --- -## 5. Register Module in Config +## 5. Add Module to Medusa's Configurations -Finally, add the module to Medusa's configurations in `medusa-config.ts`: +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`: ```ts title="medusa-config.ts" module.exports = defineConfig({ @@ -110,19 +150,33 @@ module.exports = defineConfig({ }) ``` +The Brand Module is now added to your Medusa application. You'll start using it in the [next chapter](../workflow/page.mdx). + --- ## 6. Generate and Run Migrations -To reflect the data model in the database, generate migrations for the `brandModuleService` module and migrate the changes to the database: +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. + + + +Learn more about migrations in [this chapter](../../../basics/modules/page.mdx#5-generate-migrations). + + + +[Medusa's CLI tool](!resources!/medusa-cli) 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: ```bash -npx medusa db:generate brandModuleService +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 -In the next step, you'll create a workflow whose steps use the Brand Module's main service to create a brand. +The Brand Module now creates a `brand` table in the database and provides a class to manage its records. + +In the next step, 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. diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs index eb3ee03e02..9b40491ab3 100644 --- a/www/apps/book/generated/edit-dates.mjs +++ b/www/apps/book/generated/edit-dates.mjs @@ -90,7 +90,7 @@ export const generatedEditDates = { "app/learn/advanced-development/workflows/page.mdx": "2024-09-18T08:00:57.364Z", "app/learn/advanced-development/workflows/variable-manipulation/page.mdx": "2024-11-14T16:11:24.538Z", "app/learn/customization/custom-features/api-route/page.mdx": "2024-09-12T12:42:34.201Z", - "app/learn/customization/custom-features/module/page.mdx": "2024-10-16T08:49:44.676Z", + "app/learn/customization/custom-features/module/page.mdx": "2024-11-28T09:25:29.098Z", "app/learn/customization/custom-features/workflow/page.mdx": "2024-09-30T08:43:53.133Z", "app/learn/customization/extend-models/create-links/page.mdx": "2024-09-30T08:43:53.133Z", "app/learn/customization/extend-models/extend-create-product/page.mdx": "2024-09-30T08:43:53.134Z",