asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: revise implement brand module (#10341)

Browse Source
This commit is contained in:
Shahed Nasser
2024-11-28 12:27:02 +02:00
committed by GitHub
parent 3b1a63eca7
commit 441b7adaa7
2 changed files with 78 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
www/apps/book/app/learn/customization/custom-features/module/page.mdx
View File

@@ -1,24 +1,38 @@
export const metadata = {
title: `${pageNumber} Implement Brand Module`,
title: `${pageNumber} Guide: Implement Brand Module`,
}
# {metadata.title}
<Note title="Example Chapter">
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.
<Note>
Learn more about modules in [this chapter](../../../basics/modules/page.mdx).
</Note>
## 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.
<Note>
Learn more about data models in [this chapter](../../../basics/modules/page.mdx#1-create-data-model).
</Note>
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.
<Note title="Tip">
Learn about other property types in [this chapter](../../../advanced-development/data-models/property-types/page.mdx).
</Note>
---
## 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.
<Note>
Learn more about services in [this chapter](../../../basics/modules/page.mdx#2-create-service).
</Note>
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).
<Note title="Tip">
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).
</Note>
---
## 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:
<Note>
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).
<Note title="Tip">
You export `BRAND_MODULE` to reference the module's name more reliably in other customizations.
</Note>
---
## 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.
<Note>
Learn more about migrations in [this chapter](../../../basics/modules/page.mdx#5-generate-migrations).
</Note>
[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.

2
www/apps/book/generated/edit-dates.mjs
View File

@@ -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",