docs: customization chapter exploration (#9078)

Adds a new customizations chapter with realistic example while maintaining the linear learning journey. Preview: https://docs-v2-git-docs-customizations-chapter-medusajs.vercel.app/v2/customization
2024-09-18 08:45:29 +00:00
parent 56ee4d6aad
commit 0c3e3ea88a
21 changed files with 2277 additions and 1 deletions
@@ -0,0 +1,128 @@
+export const metadata = {
+  title: `${pageNumber} Implement Brand Module`,
+}
+
+# {metadata.title}
+
+<Note title="Example Chapter">
+
+This chapter covers how to create a Brand Module as part of the ["Build Custom Features" chapter](../page.mdx).
+
+</Note>
+
+## 1. Create Module Directory
+
+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:
+
+```ts title="src/modules/brand/models/brand.ts"
+import { model } from "@medusajs/utils"
+
+export const Brand = model.define("brand", {
+  id: model.id().primaryKey(),
+  name: model.text(),
+})
+```
+
+This creates a `Brand` data model which has an `id` primary key property, and a `name` text property.
+
+---
+
+## 3. Create Module Service
+
+Next, you'll create the module's main service that manages the `Brand` data model.
+
+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."]
+]
+
+```ts title="src/modules/brand/service.ts" highlights={serviceHighlights}
+import { MedusaService } from "@medusajs/utils"
+import { Brand } from "./models/brand"
+
+class BrandModuleService extends MedusaService({
+  Brand,
+}) {
+
+}
+
+export default BrandModuleService
+```
+
+The `BrandModuleService` extends a `MedusaService` function imported from `@medusajs/utils` which is a service factory.
+
+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`.
+
+Those methods are now available at the `BrandModuleService` class and you'll use them in upcoming steps.
+
+<Note title="Tip">
+
+Find a reference of the generated methods in [this guide](!resources!/service-factory-reference).
+
+</Note>
+
+---
+
+## 4. Create Module's Definition
+
+To export the 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/utils"
+import BrandModuleService from "./service"
+
+export const BRAND_MODULE = "brandModuleService"
+
+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.
+
+<Note>
+
+Learn more about modules and services [in this guide](../../../basics/modules-and-services/page.mdx).
+
+</Note>
+
+---
+
+## 5. Register Module in Config
+
+Finally, add the module to Medusa's configurations in `medusa-config.js`:
+
+```js title="medusa-config.js"
+module.exports = defineConfig({
+  // ...
+  modules: {
+    brandModuleService: {
+      resolve: "./modules/brand",
+    },
+  },
+})
+```
+
+---
+
+## 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:
+
+```bash
+npx medusa db:generate brandModuleService
+npx medusa db:migrate
+```
+
+---
+
+## 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.