docs: small fixes and improvements to text (#14385)

2025-12-22 17:06:25 +02:00
parent b221e882d4
commit dc52dfd1dd
9 changed files with 134 additions and 210 deletions
@@ -6,18 +6,12 @@ export const metadata = {

 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](!resources!/commerce-modules/cart) that holds the data models and business logic for cart operations.
+A [module](../../../fundamentals/modules/page.mdx) 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.

 In a module, you create data models and business logic to manage them. In the next chapters, you'll see how you use the module to build commerce features.

 ![Diagram showcasing an overview of the Brand Module](https://res.cloudinary.com/dza7lstvk/image/upload/v1746546820/Medusa%20Resources/brand-module_pg86gm.jpg)

-<Note>
-
-Learn more about modules in [this chapter](../../../fundamentals/modules/page.mdx).
-
-</Note>
-
 ## 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.
@@ -28,13 +22,7 @@ Modules are created in a sub-directory of `src/modules`. So, start by creating t

 ## 2. Create Data Model

-A data model represents a table in the database. You create data models using Medusa's Data Model Language (DML). It simplifies defining a table's columns, relations, and indexes with straightforward methods and configurations.
-
-<Note>
-
-Learn more about data models in [this chapter](../../../fundamentals/modules/page.mdx#1-create-data-model).
-
-</Note>
+A [data model](../../../fundamentals/modules/page.mdx#1-create-data-model) represents a table in the database. You create data models using Medusa's Data Model Language (DML). It simplifies defining a table's columns, relations, and indexes with straightforward methods and configurations.

 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:

@@ -58,7 +46,7 @@ You define the data model using the `define` method of the DML. It accepts two p

 <Note title="Tip">

-Learn about other property types in [this chapter](../../../fundamentals/data-models/properties/page.mdx).
+Refer to the [Properties](../../../fundamentals/data-models/properties/page.mdx) chapter to learn more.

 </Note>

@@ -66,16 +54,10 @@ Learn about other property types in [this chapter](../../../fundamentals/data-mo

 ## 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.
+You perform database operations on your data models in a [service](../../../fundamentals/modules/page.mdx#2-create-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.

-<Note>
-
-Learn more about services in [this chapter](../../../fundamentals/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:

 ![Directory structure in module after adding the service](https://res.cloudinary.com/dza7lstvk/image/upload/v1732868984/Medusa%20Book/brand-dir-overview-3_jo7baj.jpg)
@@ -105,7 +87,7 @@ You'll use these methods in the [next chapter](../workflow/page.mdx).

 <Note title="Tip">

-Find a reference of all generated methods in [this guide](!resources!/service-factory-reference).
+Refer to the [service factory reference](!resources!/service-factory-reference) to learn more about the generated methods.

 </Note>

@@ -166,13 +148,7 @@ The Brand Module is now added to your Medusa application. You'll start using it

 ## 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.
-
-<Note>
-
-Learn more about migrations in [this chapter](../../../fundamentals/modules/page.mdx#5-generate-migrations).
-
-</Note>
+A [migration](../../../fundamentals/modules/page.mdx#5-generate-migrations) 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](!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:

@@ -76,7 +76,7 @@ You return in the response the retrieved brands and the pagination configuration

 <Note>

-Learn more about pagination with Query in [this chapter](../../../fundamentals/module-links/query/page.mdx#apply-pagination).
+Refer to the [Query](../../../fundamentals/module-links/query/page.mdx#apply-pagination) chapter to learn more about applying pagination when retrieving linked records.

 </Note>

@@ -138,7 +138,7 @@ By applying the above middleware, you can pass pagination configurations to `GET

 <Note>

-Learn more about using the `validateAndTransformQuery` middleware to configure Query in [this chapter](../../../fundamentals/module-links/query/page.mdx#request-query-configurations).
+Refer to the [Query](../../../fundamentals/module-links/query/page.mdx#request-query-configurations) chapter to learn more about using the `validateAndTransformQuery` middleware to configure Query.

 </Note>

@@ -176,7 +176,7 @@ You can now use the SDK to send requests to the Medusa server.

 <Note>

-Learn more about the JS SDK and its options in [this reference](!resources!/js-sdk).
+Refer to the [JS SDK Reference](!resources!/js-sdk) to learn more about the it, its options, and how to use it to send requests to Medusa's API routes.

 </Note>

@@ -188,7 +188,7 @@ You'll now add the UI route that shows the paginated list of brands. A UI route

 <Note>

-Learn more about UI routes in [this chapter](../../../fundamentals/admin/ui-routes/page.mdx).
+Refer to the [UI Routes](../../../fundamentals/admin/ui-routes/page.mdx) chapter to learn more about UI routes.

 </Note>

@@ -48,13 +48,13 @@ You initialize the SDK passing it the following options:
 - `debug`: Whether to enable logging debug messages. This should only be enabled in development.
 - `auth.type`: The authentication method used in the client application, which is `session` in the Medusa Admin dashboard.

-Notice that you use `import.meta.env` to access environment variables in your customizations because the Medusa Admin is built on top of Vite. Learn more in [this chapter](../../../fundamentals/admin/environment-variables/page.mdx).
+Notice that you use `import.meta.env` to access environment variables in your customizations because the Medusa Admin is built on top of Vite. Learn more in the [Admin Environment Variables](../../../fundamentals/admin/environment-variables/page.mdx) chapter.

 You can now use the SDK to send requests to the Medusa server.

 <Note>

-Learn more about the JS SDK and its options in [this reference](!resources!/js-sdk).
+Refer to the [JS SDK Reference](!resources!/js-sdk) to learn more about the it, its options, and how to use it to send requests to Medusa's API routes.

 </Note>

@@ -62,13 +62,7 @@ Learn more about the JS SDK and its options in [this reference](!resources!/js-s

 ## 2. Add Widget to Product Details Page

-You'll now add a widget to the product-details page. A widget is a React component that's injected into pre-defined zones in the Medusa Admin dashboard. It's created in a `.tsx` file under the `src/admin/widgets` directory.
-
-<Note>
-
-Learn more about widgets in [this documentation](../../../fundamentals/admin/widgets/page.mdx).
-
-</Note>
+You'll now add a widget to the product-details page. A [widget](../../../fundamentals/admin/widgets/page.mdx) is a React component that's injected into pre-defined zones in the Medusa Admin dashboard. It's created in a `.tsx` file under the `src/admin/widgets` directory.

 To create a widget that shows a product's brand in its details page, create the file `src/admin/widgets/product-brand.tsx` with the following content:

@@ -13,18 +13,12 @@ export const metadata = {

 In this chapter, you'll learn how to define a module link between a brand defined in the [custom Brand Module](../../custom-features/module/page.mdx), and a product defined in the [Product Module](!resources!/commerce-modules/product) that's available in your Medusa application out-of-the-box.

-Modules are [isolated](../../../fundamentals/modules/isolation/page.mdx) from other resources, ensuring that they're integrated into the Medusa application without side effects. However, you may need to associate data models of different modules, or you're trying to extend data models from Commerce Modules with custom properties. To do that, you define module links.
+Modules are [isolated](../../../fundamentals/modules/isolation/page.mdx) from other resources, ensuring that they're integrated into the Medusa application without side effects. However, you may need to build relations between data models of different modules, or you're trying to extend data models from [Commerce Modules](!resources!/commerce-modules) with custom properties. To do that, you define module links.

-A module link forms an association between two data models of different modules while maintaining module isolation. You can then manage and query linked records of the data models using Medusa's Modules SDK.
+A [module link](../../../fundamentals/module-links/page.mdx) forms an association between two data models of different modules while maintaining module isolation. You can then manage and query linked records of the data models using Medusa's Modules SDK.

 In this chapter, you'll define a module link between the `Brand` data model of the Brand Module, and the `Product` data model of the Product Module. In later chapters, you'll manage and retrieve linked product and brand records.

-<Note>
-
-Learn more about module links in [this chapters](../../../fundamentals/module-links/page.mdx).
-
-</Note>
-
 <Prerequisites
  items={[
    {
@@ -22,7 +22,7 @@ So, in this chapter, to extend the create product flow and associate a brand wit

 <Note>

-To learn more about the `additional_data` property and the API routes that accept additional data, refer to [this chapter](../../../fundamentals/api-routes/additional-data/page.mdx).
+To learn more about the `additional_data` property and the API routes that accept additional data, refer to the [Additional Data](../../../fundamentals/api-routes/additional-data/page.mdx) chapter.

 </Note>

@@ -43,13 +43,7 @@ To learn more about the `additional_data` property and the API routes that accep

 ## 1. Consume the productsCreated Hook

-A workflow hook is a point in a workflow where you can inject a step to perform a custom functionality. Consuming a workflow hook allows you to extend the features of a workflow and, consequently, the API route that uses it.
-
-<Note>
-
-Learn more about the workflow hooks in [this chapter](../../../fundamentals/workflows/workflow-hooks/page.mdx).
-
-</Note>
+A [workflow hook](../../../fundamentals/workflows/workflow-hooks/page.mdx) is a point in a workflow where you can inject a step to perform a custom functionality. Consuming a workflow hook allows you to extend the features of a workflow and, consequently, the API route that uses it.

 The [createProductsWorkflow](!resources!/references/medusa-workflows/createProductsWorkflow) used in the [Create Product API route](!api!/admin#products_postproducts) has a `productsCreated` hook that runs after the product is created. You'll consume this hook to link the created product with the brand specified in the request parameters.

@@ -98,13 +92,7 @@ In the step, if a brand ID is passed in `additional_data`, you resolve the Brand

 ### Link Brand to Product

-Next, you want to create a link between the created products and the brand. To do so, you use Link, which is a class from the Modules SDK that provides methods to manage linked records.
-
-<Note>
-
-Learn more about Link in [this chapter](../../../fundamentals/module-links/link/page.mdx).
-
-</Note>
+Next, you want to create a link between the created products and the brand. To do so, you use [Link](../../../fundamentals/module-links/link/page.mdx), which is a class from the Modules SDK that provides methods to manage linked records.

 To use Link in the `productsCreated` hook, replace the `TODO` with the following:

@@ -139,7 +127,7 @@ logger.info("Linked brand to products")
 return new StepResponse(links, links)
 ```

-You resolve Link from the container. Then you loop over the created products to assemble an array of links to be created. After that, you pass the array of links to Link's `create` method, which will link the product and brand records.
+You resolve Link from the container. Then, you loop over the created products to assemble an array of links to be created. After that, you pass the array of links to Link's `create` method, which will link the product and brand records.

 Each property in the link object is the name of a module, and its value is an object having a `{model_name}_id` property, where `{model_name}` is the snake-case name of the module's data model. Its value is the ID of the record to be linked. The link object's properties must be set in the same order as the link configurations passed to `defineLink`.

@@ -44,7 +44,7 @@ For example, send the following request to retrieve the list of products with th

 ```bash
 curl 'http://localhost:9000/admin/products?fields=+brand.*' \
--header 'Authorization: Bearer {token}'
+-H 'Authorization: Bearer {token}'
 ```

 <Note title="Tip">
@@ -75,19 +75,13 @@ By using the `fields` query parameter, you don't have to re-create existing API

 While you can retrieve linked records using the `fields` query parameter of an existing API route, you can't filter by linked records.

-Instead, you'll have to create a custom API route that uses Query to retrieve linked records with filters, as explained in the [Query documentation](../../../fundamentals/module-links/query/page.mdx#apply-filters-and-pagination-on-linked-records).
+Instead, you'll have to create a custom API route that uses [Query](../../../fundamentals/module-links/query/page.mdx#apply-filters-and-pagination-on-linked-records) to retrieve linked records with filters.

 ---

 ## Approach 2: Use Query to Retrieve Linked Records

-You can also retrieve linked records using Query. Query allows you to retrieve data across modules with filters, pagination, and more. You can resolve Query from the Medusa container and use it in your API route or workflow.
-
-<Note>
-
-Learn more about Query in [this chapter](../../../fundamentals/module-links/query/page.mdx).
-
-</Note>
+You can also retrieve linked records using [Query](../../../fundamentals/module-links/query/page.mdx). Query allows you to retrieve data across modules with filters, pagination, and more. You can resolve Query from the Medusa container and use it in your API route or workflow.

 For example, you can create an API route that retrieves brands and their products. If you followed the [Create Brands API route chapter](../../custom-features/api-route/page.mdx), you'll have the file `src/api/admin/brands/route.ts` with a `POST` API route. Add a new `GET` function to the same file:

@@ -183,6 +177,6 @@ By following the examples of the previous chapters, you:

 ## Next Steps: Customize Medusa Admin

-Clients, such as the Medusa Admin dashboard, can now use brand-related features, such as creating a brand or setting the brand of a product.
+Client applications, such as the Medusa Admin dashboard, can now use brand-related features, such as creating a brand or setting the brand of a product.

 In the next chapters, you'll learn how to customize the Medusa Admin to show a product's brand on its details page, and to show a new page with the list of brands in your store.