diff --git a/www/apps/book/app/basics/admin-customizations/page.mdx b/www/apps/book/app/basics/admin-customizations/page.mdx index e1719d93c7..3a2695a03d 100644 --- a/www/apps/book/app/basics/admin-customizations/page.mdx +++ b/www/apps/book/app/basics/admin-customizations/page.mdx @@ -6,7 +6,7 @@ export const metadata = { In this chapter, you’ll learn how to customize the Medusa Admin dashboard. -## Overview +## What is the Medusa Admin? The Medusa Admin is an admin dashboard that merchants use to manage their store's data. diff --git a/www/apps/book/app/basics/commerce-modules/page.mdx b/www/apps/book/app/basics/commerce-modules/page.mdx index 3d744abbb5..a673ee45f0 100644 --- a/www/apps/book/app/basics/commerce-modules/page.mdx +++ b/www/apps/book/app/basics/commerce-modules/page.mdx @@ -8,9 +8,11 @@ In this chapter, you'll learn about Medusa's commerce modules. ## What is a Commerce Module? -Medusa provides all its commerce features as separate modules, such as the Product or Order modules. +Medusa provides all its commerce features as separate commerce modules, such as the Product or Order modules. Medusa uses these modules in its API routes to expose their commerce features. -These modules and your custom modules are interchangeable in the Medusa application, making Medusa’s architecture more flexible. +Medusa's commerce modules and your custom modules are interchangeable in the Medusa application, making Medusa’s architecture more flexible. + +### List of Medusa's Commerce Modules Refer to [this reference](!resources!/commerce-modules) for a full list of commerce modules in Medusa. diff --git a/www/apps/book/app/basics/data-models/page.mdx b/www/apps/book/app/basics/data-models/page.mdx index 72b387813a..0d488b8d94 100644 --- a/www/apps/book/app/basics/data-models/page.mdx +++ b/www/apps/book/app/basics/data-models/page.mdx @@ -8,7 +8,9 @@ In this chapter, you’ll learn what data models are and how to create a data mo ## What is a Data Model? -A data model is a class that represents a table in the database. It's created in a module. +A data model is a class that represents a table in the database. + +A data model is created in a module, and its record are managed in the database using the module's service. --- @@ -46,7 +48,7 @@ The example above defines the data model `MyCustom` with the properties `id` and ### Generate a Migration -A migration defines changes to be made in the database, such as create or update tables. +A migration is a TypeScript or JavaScript file that defines changes to be made in the database, such as create or update tables. To generate a migration for the data models in your module, run the following command: diff --git a/www/apps/book/app/basics/events-and-subscribers/page.mdx b/www/apps/book/app/basics/events-and-subscribers/page.mdx index 8f39fd2bb1..0e14608452 100644 --- a/www/apps/book/app/basics/events-and-subscribers/page.mdx +++ b/www/apps/book/app/basics/events-and-subscribers/page.mdx @@ -8,7 +8,9 @@ In this chapter, you’ll learn how to handle events with subscribers. ## What is an Event? -When an action is performed in Medusa, such as creating a product, the Medusa application emits an event. You can listen to those events and perform an asynchronous action. +When an action is performed in Medusa, such as creating a product, the Medusa application emits an event. + +You can listen to those events and perform an asynchronous action using a subscriber. --- diff --git a/www/apps/book/app/basics/loaders/page.mdx b/www/apps/book/app/basics/loaders/page.mdx index a35e16a110..0be653a04b 100644 --- a/www/apps/book/app/basics/loaders/page.mdx +++ b/www/apps/book/app/basics/loaders/page.mdx @@ -10,6 +10,8 @@ In this chapter, you’ll learn about loaders and how to use them. A loader is a function executed when the Medusa application starts. You define and export it in a module. +Loaders are useful to perform a task at the application start-up, such as to sync data between Medusa and a third-pary service. + --- ## How to Create a Loader? diff --git a/www/apps/book/app/basics/medusa-container/page.mdx b/www/apps/book/app/basics/medusa-container/page.mdx index 8fa9a62c07..3fb529144e 100644 --- a/www/apps/book/app/basics/medusa-container/page.mdx +++ b/www/apps/book/app/basics/medusa-container/page.mdx @@ -4,13 +4,13 @@ export const metadata = { # {metadata.title} -In this chapter, you’ll learn about Medusa’s Medusa container and how to use it. +In this chapter, you’ll learn about the Medusa container and how to use it. ## What is the Medusa container? -The Medusa container holds all resources registered in the Medusa application. You have access to it in your customizations. +The Medusa container holds all resources registered in the Medusa application, such as services. -You use the Medusa container to resolve resources, such as services. +In your customizations, you use the Medusa container to resolve these resources and use their functionalities. For example, in a custom API route you can resolve any service registered in the Medusa application using the `scope.resolve` method of the `MedusaRequest` parameter: diff --git a/www/apps/book/app/basics/modules-and-services/page.mdx b/www/apps/book/app/basics/modules-and-services/page.mdx index 207c704d4c..7e9a49db47 100644 --- a/www/apps/book/app/basics/modules-and-services/page.mdx +++ b/www/apps/book/app/basics/modules-and-services/page.mdx @@ -8,9 +8,9 @@ In this chapter, you’ll learn about modules, their main service, and how to cr ## What is a Module? -A module is a package of reusable functionalities. It can be integrated into your Medusa application without affecting the overall system. +A module is a package of reusable commerce or architectural functionalities. It's integrated as a building block in your Medusa application, without implications on the existing setup. -Use modules to customize or develop commerce and architectural features in your Medusa application. +You create a module to introduce custom features, extend existing ones, or integrate third-party services. --- @@ -30,7 +30,9 @@ For example, create the directory `src/modules/hello`. ### 1. Create Main Service -A module must define a service. A service is a TypeScript or JavaScript class holding methods related to a business logic or commerce functionality. It must be defined at the root of your module directory under `service.ts` filename. +A module must define a service. A service is a TypeScript or JavaScript class used to perform actions on the database or connect to third-party services. + +A service must be defined at the root of your module directory under `service.ts` filename. For example, create the file `src/modules/hello/service.ts` with the following content: @@ -81,7 +83,13 @@ module.exports = defineConfig({ }) ``` -Its key (`helloModuleService`) is the name of the module’s main service. It will be registered in the Medusa container with that name. It should also be the same name passed as the first parameter to the `Module` function in the module's definition. +Its key (`helloModuleService`) is the name of the module’s main service. It will be registered in the Medusa container with that name. + + + +It should also be the same name passed as the first parameter to the `Module` function in the module's definition. + + Its value is an object having the `resolve` property, whose value is either a path to module's directory relative to `src`(it shouldn't include `src` in the path), or an `npm` package’s name. @@ -89,7 +97,13 @@ Its value is an object having the `resolve` property, whose value is either a pa ## Test the Module -Since the module's main service is registered in the Medusa container, you can resolve it in other resources to use its functionalities. +Since the module's main service is registered in the Medusa container, you can resolve it in other resources to use its methods. + + + +Resolving a module's service is essential to use its methods that perform actions on the database or connect to a third-party service. + + For example, create the API route `src/api/store/custom/route.ts` with the following content: diff --git a/www/apps/book/app/basics/page.mdx b/www/apps/book/app/basics/page.mdx index 51bedc4967..0be88bc387 100644 --- a/www/apps/book/app/basics/page.mdx +++ b/www/apps/book/app/basics/page.mdx @@ -10,7 +10,7 @@ By the end of these chapter, you’ll be able to: - Expose your custom functionalities through endpoints. - Create custom modules that define custom business logic. -- Create custom data models. +- Create custom tables in the database through data models. - Execute scripts when the Medusa application starts. - Perform asynchronus actions when an event occurs. - Run tasks at a specified time or pattern during the Medusa application's runtime. diff --git a/www/apps/book/app/basics/workflows/page.mdx b/www/apps/book/app/basics/workflows/page.mdx index 879a5d57e8..3880a8e3a2 100644 --- a/www/apps/book/app/basics/workflows/page.mdx +++ b/www/apps/book/app/basics/workflows/page.mdx @@ -12,7 +12,9 @@ In this chapter, you’ll learn about workflows and how to define and execute th A workflow is a series of queries and actions that complete a task. -You construct a workflow similar to how you create a JavaScript function, but unlike regular functions, a workflow creates an internal representation of your steps. This makes it possible to keep track of your workflow’s progress, automatically retry failing steps, and roll back steps. +You construct a workflow similar to how you create a JavaScript function, but unlike regular functions, a workflow creates an internal representation of your steps. + +By using a workflow, you can track its execution's progress, provide roll-back logic for each step to mitigate data inconsistency when errors occur, automatically retry failing steps, and do much more, as explained in later chapters. --- @@ -213,7 +215,7 @@ You’ll receive the following response: - You're defining a flow with interactions across multiple systems and services. - You're defining flows to be used across different resources. For example, if you want to invoke the flow manually through an API Router, but also want to automate its running through a scheduled job. -- You want to define configurations related to errors and how to roll-back steps. This is explained more in later chapters. +- You want to maintain data consistency and handle errors gracefully by rolling-back steps. This is explained more in later chapters. diff --git a/www/apps/book/app/page.mdx b/www/apps/book/app/page.mdx index 08b6d0dfd0..a84f661918 100644 --- a/www/apps/book/app/page.mdx +++ b/www/apps/book/app/page.mdx @@ -95,7 +95,7 @@ Medusa is for ambitious businesses and developers that are limited by traditiona ## Who is this documentation for -This documentation is for TypeScript or JavaScript developers looking to master Medusa and build their commerce applications. By following this documentation, you’ll learn about Medusa’s concept, from basic to advanced, with easy-to-follow examples to assist you along the way. +This documentation is for TypeScript or JavaScript developers looking to master Medusa and build their commerce applications. By following this documentation, you’ll learn about Medusa’s concepts, from basic to advanced, with easy-to-follow examples to assist you along the way. By the end of this documentation, you’ll be an expert Medusa developer, leading teams using Medusa from the development till production. @@ -104,5 +104,5 @@ By the end of this documentation, you’ll be an expert Medusa developer, leadin The documentation for Medusa v2 is split into the following sections: 1. The main documentation, which is the one you're currently viewing. It's highly recommended to follow all the chapters in this documentation before jumping into other documentation sections. -2. The [Learning Resources documentation](!resources!) provides guides and resources useful during your development, such as tool API references, recipes, step-by-step guides and examples, and more. +2. The [Learning Resources documentation](!resources!) provides guides and resources useful during your development, such as tools, API references, recipes, step-by-step guides and examples, and more. 3. The [Store](!api!/store) and [Admin](!api!/admin) API references provide a reference to the Medusa application's endpoints and instructions related to authentication, parameter types, and more. diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs index cc9a8e4afe..c3f02492c5 100644 --- a/www/apps/book/generated/edit-dates.mjs +++ b/www/apps/book/generated/edit-dates.mjs @@ -1,10 +1,10 @@ export const generatedEditDates = { "app/basics/scheduled-jobs/page.mdx": "2024-08-05T07:24:27+00:00", - "app/basics/workflows/page.mdx": "2024-08-05T07:24:27+00:00", + "app/basics/workflows/page.mdx": "2024-09-03T08:07:16.276Z", "app/deployment/page.mdx": "2024-08-05T07:24:05+00:00", - "app/page.mdx": "2024-07-24T14:16:33+00:00", - "app/basics/modules-and-services/page.mdx": "2024-07-15T16:00:54+00:00", - "app/basics/commerce-modules/page.mdx": "2024-08-05T07:24:27+00:00", + "app/page.mdx": "2024-09-03T07:09:09.034Z", + "app/basics/modules-and-services/page.mdx": "2024-09-03T07:45:28.079Z", + "app/basics/commerce-modules/page.mdx": "2024-09-03T07:48:48.148Z", "app/advanced-development/workflows/retry-failed-steps/page.mdx": "2024-07-31T17:01:33+03:00", "app/advanced-development/workflows/workflow-hooks/page.mdx": "2024-08-13T09:55:37+03:00", "app/cheatsheet/page.mdx": "2024-07-11T13:53:40+03:00", @@ -13,24 +13,24 @@ export const generatedEditDates = { "app/more-resources/page.mdx": "2024-07-04T17:26:03+03:00", "app/storefront-development/page.mdx": "2024-07-04T17:26:03+03:00", "app/storefront-development/nextjs-starter/page.mdx": "2024-07-04T17:26:03+03:00", - "app/basics/page.mdx": "2024-07-04T17:26:03+03:00", - "app/basics/admin-customizations/page.mdx": "2024-07-04T17:26:03+03:00", + "app/basics/page.mdx": "2024-09-03T07:11:06.879Z", + "app/basics/admin-customizations/page.mdx": "2024-09-03T08:07:35.584Z", "app/advanced-development/workflows/workflow-timeout/page.mdx": "2024-07-31T17:01:33+03:00", "app/advanced-development/workflows/parallel-steps/page.mdx": "2024-07-31T17:01:33+03:00", "app/advanced-development/page.mdx": "2024-07-04T17:26:03+03:00", "app/first-customizations/page.mdx": "2024-05-07T18:00:28+02:00", "app/debugging-and-testing/page.mdx": "2024-05-03T17:36:38+03:00", - "app/basics/medusa-container/page.mdx": "2024-08-05T07:24:27+00:00", + "app/basics/medusa-container/page.mdx": "2024-09-03T07:31:40.214Z", "app/architectural-modules/page.mdx": "2024-07-04T17:26:03+03:00", "app/basics/project-directories-files/page.mdx": "2024-07-04T17:26:03+03:00", "app/basics/api-routes/page.mdx": "2024-07-04T17:26:03+03:00", "app/basics/modules-directory-structure/page.mdx": "2024-05-07T18:00:28+02:00", "app/advanced-development/workflows/access-workflow-errors/page.mdx": "2024-07-04T17:26:03+03:00", - "app/basics/events-and-subscribers/page.mdx": "2024-08-05T07:24:27+00:00", + "app/basics/events-and-subscribers/page.mdx": "2024-09-03T08:01:30.986Z", "app/advanced-development/modules/container/page.mdx": "2024-08-05T07:23:49+00:00", - "app/basics/data-models/page.mdx": "2024-07-15T17:46:10+02:00", + "app/basics/data-models/page.mdx": "2024-09-03T07:58:42.761Z", "app/advanced-development/workflows/execute-another-workflow/page.mdx": "2024-07-21T21:19:23+02:00", - "app/basics/loaders/page.mdx": "2024-08-05T07:23:49+00:00", + "app/basics/loaders/page.mdx": "2024-09-03T08:00:45.993Z", "app/advanced-development/admin/widgets/page.mdx": "2024-08-06T09:44:22+02:00", "app/advanced-development/data-models/page.mdx": "2024-07-04T17:26:03+03:00", "app/advanced-development/modules/remote-link/page.mdx": "2024-07-24T09:16:01+02:00",