docs: update modules chapter in basics #9452
Conversation
shahednasser
commented
Oct 3, 2024
shahednasser
commented
- Replace the data models and modules and services chapters in basics with a single modules chapter that covers the three concepts
- Add redirects from the old chapters to the new one + fix links
|
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
1 Skipped Deployment
|
| A module is a package of reusable commerce or architectural functionalities. These functionalities are implemented within the module in a class called a service. | ||
|
|
||
| In the module, you can create new tables in the database. Then, you manage their records using the module's service, which connects to the database. | ||
|
|
||
| A module is integrated as a building block in your Medusa application, without implications on the existing setup. | ||
|
|
||
| <Note title="Tip"> | ||
|
|
||
| Modules and services have other uses too, which you'll learn about in later chapters. | ||
|
|
||
| </Note> |
There was a problem hiding this comment.
suggestion:
In Medusa, Modules handle business logic and define and manage data models. Out of the box, Medusa comes with multiple pre-built modules for core commerce needs. An example is the Cart module, which holds the data models and business logic for cart operations.
In digital commerce you often need to introduce custom behavior specific to your products, industry, tech stack, or your general ways of working. In other commerce platforms introducing custom business logic and data models requires setting up separate applications to manage these customizations, but Medusa removes the overhead of doing that by enabling you to easily write custom Modules that can interact with the rest of Medusa.
As you learn more about Medusa you will see that Modules are central to customizations and integrations. In this section you will build a module that comprise a data model and a corresponding module service to manage the data model.
There was a problem hiding this comment.
I like this, but how about we use some for this intro section (what is a module), and some in a later section (why use modules)? I just think it could be too much information from the get-go, especially if you haven't seen it in action yet. We'd be jumping 10 steps ahead before the developer had a glimpse of what a module entails.
| ## How to Create a Module? | ||
|
|
||
| Modules are created in a sub-directory of `src/modules`. | ||
|
|
||
| For example, create the directory `src/modules/hello`. | ||
|
|
||
| ### 1. Create Data Model | ||
|
|
||
| A data model represents a table in the database. It's created in a TypeScript or JavaScript file under the module's `models` directory. | ||
|
|
There was a problem hiding this comment.
thought: feel like there is a need for setting the agenda for the steps that are coming. Just one sentence on the high-level objective here would be helpful.
E.g.: "In the following steps we will create a data model called MyCustom, we will then add a ModuleService to manage that data model, and finally we will use the module in an API route."
| Since the module has data models, its service extends a class generated by the service factory function `MedusaService` imported from `@medusajs/framework/utils`. | ||
|
|
||
| <Note title="Tip"> | ||
|
|
||
| If a module doesn't have data models, it doesn't need to extend `MedusaService`. | ||
|
|
||
| </Note> | ||
|
|
||
| The service factory function accepts as a parameter an object of data models. It returns a service class with data management methods, such as `createMyCustoms` or `retrieveMyCustoms`. | ||
|
|
||
| Your service extends the returned class to benefit from the generated methods. |
There was a problem hiding this comment.
suggestion:
In the snippet above, your module service extends MedusaService. MedusaService can take a set of data models and will generate a class that has implementations for the CRUD operations on those data models. For example, the HelloModuleService now allows you to do createMyCustoms or retrieveMyCustoms.
Using MedusaService is not required, but it is helpful and recommended when your module has data models.
* docs: update modules chapter in basics * address PR feedback
