diff --git a/www/apps/resources/app/recipes/digital-products/examples/standard/page.mdx b/www/apps/resources/app/recipes/digital-products/examples/standard/page.mdx index 5f88ad4b9d..9daf3d52c3 100644 --- a/www/apps/resources/app/recipes/digital-products/examples/standard/page.mdx +++ b/www/apps/resources/app/recipes/digital-products/examples/standard/page.mdx @@ -51,7 +51,11 @@ By following this example, you’ll have a commerce application with the followi ## Step 1: Create the Digital Product Module -The first step is to create a digital product module that holds the data models related to a digital product. +Medusa creates commerce features in modules. For example, product features and data models are created in the Product Module. + +You also create custom commerce data models and features in custom modules. They're integrated into the Medusa application similar to Medusa's modules without side effects. + +So, you'll create a digital product module that holds the data models related to a digital product and allows you to manage them. Create the directory `src/modules/digital-product`. @@ -211,7 +215,16 @@ module.exports = defineConfig({ ## Step 2: Define Links -In this step, you’ll define links between your module’s data models and data models from Medusa’s commerce modules. +Modules are isolated in Medusa, making them reusable, replaceable, and integrable in your application without side effects. + +So, you can't have relations between data models in modules. Instead, you define a link between them. + +Links are relations between data models of different modules that maintain the isolation between the modules. + +In this step, you’ll define links between your module’s data models and data models from Medusa’s commerce modules: + +1. Link between the `DigitalProduct` model and the Product Module's `ProductVariant` model. +2. Link between the `DigitalProductOrder` model and the Order Module's `Order` model. Start by creating the file `src/links/digital-product-variant.ts` with the following content: @@ -279,6 +292,8 @@ npx medusa db:migrate ## Step 4: List Digital Products Admin API Route +To expose custom commerce features to frontend applications, such as the Medusa Admin dashboard or a storefront, you expose an endpoint by creating an API route. + In this step, you’ll create the admin API route to list digital products. Create the file `src/api/admin/digital-products/route.ts` with the following content: @@ -368,7 +383,9 @@ Make sure to replace `{token}` with the JWT token you retrieved. ## Step 5: Create Digital Product Workflow -In this step, you’ll create a workflow that creates a digital product. You’ll use this workflow in the next section. +To implement and expose a feature that manipulates data, you create a workflow that uses services to implement the functionality, then create an API route that executes that workflow. + +In this step, you’ll create a workflow that creates a digital product. You’ll use this workflow in an API route in the next section. This workflow has the following steps: @@ -617,7 +634,7 @@ You’ll test out the workflow in the next section. ## Step 6: Create Digital Product API Route -In this step, you’ll add the API route to create a digital product. +In this step, you’ll add the API route to create a digital product using the `createDigitalProductWorkflow`. In the file `src/api/admin/digital-products/route.ts` add a new route handler: @@ -716,9 +733,7 @@ This adds a validation middleware to ensure that the body of `POST` requests sen ## Step 7: Upload Digital Product Media API Route -To upload the digital product media files, use Medusa’s file module. - -In this step, you’ll create an API route for uploading preview and main digital product media files. +To upload the digital product media files, use Medusa’s File Module. @@ -726,6 +741,8 @@ Your Medusa application uses the local file module provider by default, which up +In this step, you’ll create an API route for uploading preview and main digital product media files. + Before creating the API route, install the [multer express middleware](https://expressjs.com/en/resources/middleware/multer.html) to support file uploads: ```bash npm2yarn @@ -809,6 +826,8 @@ You’ll test out this API route in the next step as you use these API routes in ## Step 8: Add Digital Products UI Route in Admin +The Medusa Admin is customizable, allowing you to inject widgets into existing pages or add UI routes to create new pages. + In this step, you’ll add a UI route to the Medusa Admin that displays a list of digital products. Before you create the UI route, create the file `src/admin/types/index.ts` that holds the following types: @@ -1819,7 +1838,7 @@ In a later step, you’ll add an API route to allow customers to view and downlo ## Step 12: Fulfill Digital Order Workflow -In this step, you'll create a workflow that fulfills a digital order by sending a notification to the customer. Later, you'll execute this workflow in a subscriber. +In this step, you'll create a workflow that fulfills a digital order by sending a notification to the customer. Later, you'll execute this workflow in a subscriber that listens to the `digital_product_order.created` event. The workflow has the following steps: @@ -2031,6 +2050,8 @@ module.exports = defineConfig({ ## Step 13: Handle the Digital Product Order Event +A subscriber is an asynchronous function that, when an event is emitted, is executed. You can implement in subscribers features that aren't essential to the original flow that emitted the event. + In this step, you'll create a subscriber that listens to the `digital_product_order.created` event and executes the workflow from the above step. Create the file `src/subscribers/handle-digital-order.ts` with the following content: diff --git a/www/apps/resources/app/recipes/marketplace/examples/restaurant-delivery/page.mdx b/www/apps/resources/app/recipes/marketplace/examples/restaurant-delivery/page.mdx index b6e8ba7737..4964ce3332 100644 --- a/www/apps/resources/app/recipes/marketplace/examples/restaurant-delivery/page.mdx +++ b/www/apps/resources/app/recipes/marketplace/examples/restaurant-delivery/page.mdx @@ -65,7 +65,11 @@ This recipe is adapted from [Medusa Eats](https://github.com/medusajs/medusa-eat ## Step 1: Create a Restaurant Module -In this step, you’ll create a Restaurant Module that defines the models related to a restaurant. +Medusa creates commerce features in modules. For example, product features and data models are created in the Product Module. + +You also create custom commerce data models and features in custom modules. They're integrated into the Medusa application similar to Medusa's modules without side effects. + +So, you'll create a restaurant module that holds the data models related to a restaurant and allows you to manage them. Create the directory `src/modules/restaurant`. @@ -317,7 +321,18 @@ module.exports = defineConfig({ ## Step 3: Define Links -In this step, you’ll define links between the Restaurant and Delivery modules, and other modules. +Modules are isolated in Medusa, making them reusable, replaceable, and integrable in your application without side effects. + +So, you can't have relations between data models in modules. Instead, you define a link between them. + +Links are relations between data models of different modules that maintain the isolation between the modules. + +In this step, you’ll define links between the Restaurant and Delivery modules, and other modules: + +1. Link between the `Restaurant` model and the Product Module's `Product` model. +2. Link between the `Restaurant` model and the Delivery Module's `Delivery` model. +3. Link between the `Delivery` model and the Cart Module's `Cart` model. +4. Link between the `Delivery` model and the Order Module's `Order` model. ### Restaurant \<> Product Link @@ -425,6 +440,8 @@ npx medusa db:migrate ## Step 5: Create Restaurant API Route +To expose custom commerce features to frontend applications, such as the Medusa Admin dashboard or a storefront, you expose an endpoint by creating an API route. + In this step, you’ll create the API route used to create a restaurant. This route requires no authentication, as anyone can create a restaurant. ### Create Types @@ -704,7 +721,9 @@ Medusa provides an authentication flow that allows you to authenticate custom us ### Create Workflow -Start by implementing the functionality to create a user in a workflow. The workflow has two steps: +To implement and expose a feature that manipulates data, you create a workflow that uses services to implement the functionality, then create an API route that executes that workflow. + +So, you'll start by implementing the functionality to create a user in a workflow. The workflow has two steps: 1. Create the user in the database. 2. Set the actor type of the user’s authentication identity (created by the `/auth/{actor_type}/{provider}/register` API route). For this step, you’ll use the `setAuthAppMetadataStep` step imported from the `@medusajs/medusa/core-flows` package. @@ -882,7 +901,7 @@ In the workflow, you: ### Create API Route -You’ll now create the API route to create a new user. +You’ll now create the API route to create a new user using the `createUserWorkflow`. Start by creating the file `src/api/users/validation-schemas.ts` that holds the schema necessary to validate the request body: @@ -938,6 +957,8 @@ This creates a `POST` API route at `/users` that creates a driver or a restauran ### Add Authentication Middleware +A middleware is executed when an HTTP request is received and before the route handler. It can be used to guard routes based on restrictions or authentication. + The `/users` API route must only be accessed with the authentication token in the header. So, you must add an authentication middleware on the route. Create the file `src/api/middlewares.ts` with the following content: diff --git a/www/apps/resources/app/recipes/marketplace/examples/vendors/page.mdx b/www/apps/resources/app/recipes/marketplace/examples/vendors/page.mdx index bcc96a9a6f..748bfc935a 100644 --- a/www/apps/resources/app/recipes/marketplace/examples/vendors/page.mdx +++ b/www/apps/resources/app/recipes/marketplace/examples/vendors/page.mdx @@ -50,7 +50,11 @@ By following this example, you’ll have a marketplace with the following featur ## Step 1: Create Marketplace Module -The first step is to create a marketplace module that holds the data models for a vendor and an admin. +Medusa creates commerce features in modules. For example, product features and data models are created in the Product Module. + +You also create custom commerce data models and features in custom modules. They're integrated into the Medusa application similar to Medusa's modules without side effects. + +So, you'll create a marketplace module that holds the data models for a vendor and an admin and allows you to manage them. Create the directory `src/modules/marketplace`. @@ -157,6 +161,12 @@ module.exports = defineConfig({ ## Step 2: Define Links to Product and Order Data Models +Modules are isolated in Medusa, making them reusable, replaceable, and integrable in your application without side effects. + +So, you can't have relations between data models in modules. Instead, you define a link between them. + +Links are relations between data models of different modules that maintain the isolation between the modules. + Each vendor has products and orders. So, in this step, you’ll define links between the `Vendor` data model and the `Product` and `Order` data models from the Product and Order modules, respectively. @@ -227,7 +237,9 @@ npx medusa db:migrate ## Step 4: Create Vendor Admin Workflow -In this step, you’ll create the workflow used to create a vendor admin. +To implement and expose a feature that manipulates data, you create a workflow that uses services to implement the functionality, then create an API route that executes that workflow. + +In this step, you’ll create the workflow used to create a vendor admin. You'll use it in the next step in an API route. The workflow’s steps are: @@ -347,6 +359,8 @@ You return the created vendor admin. ## Step 5: Create Vendor API Route +To expose custom commerce features to frontend applications, such as the Medusa Admin dashboard or a storefront, you expose an endpoint by creating an API route. + In this step, you’ll create the API route that runs the workflow from the previous step. Start by creating the file `src/api/vendors/route.ts` with the following content: diff --git a/www/apps/resources/app/recipes/subscriptions/examples/standard/page.mdx b/www/apps/resources/app/recipes/subscriptions/examples/standard/page.mdx index 23614cd2e5..b6847ded6a 100644 --- a/www/apps/resources/app/recipes/subscriptions/examples/standard/page.mdx +++ b/www/apps/resources/app/recipes/subscriptions/examples/standard/page.mdx @@ -51,7 +51,11 @@ By following this example, you’ll have a subscription commerce store with the ## Step 1: Create Subscription Module -The first step is to create a subscription module that holds the subscription's data model and provides data-management features through its service. +Medusa creates commerce features in modules. For example, product features and data models are created in the Product Module. + +You also create custom commerce data models and features in custom modules. They're integrated into the Medusa application similar to Medusa's modules without side effects. + +So, you'll create a subscription module that holds the data models related to a subscription and allows you to manage them. Create the directory `src/modules/subscription`. @@ -176,7 +180,17 @@ module.exports = defineConfig({ ## Step 2: Define Links -In this step, you’ll define links between the Subscription Module’s `Subscription` data model and the data models of Medusa’s commerce modules. +Modules are isolated in Medusa, making them reusable, replaceable, and integrable in your application without side effects. + +So, you can't have relations between data models in modules. Instead, you define a link between them. + +Links are relations between data models of different modules that maintain the isolation between the modules. + +In this step, you’ll define links between the Subscription Module’s `Subscription` data model and the data models of Medusa’s commerce modules: + +1. Link between the `Subscription` data model and the Cart Module's `Cart` model. +2. Link between the `Subscription` data model and the Customer Module's `Customer` model. +3. Link between the `Subscription` data model and the Order Module's `Order` model. ### Define a Link to Cart @@ -436,6 +450,8 @@ This method is used in the next step. ## Step 5: Create Subscription Workflow +To implement and expose a feature that manipulates data, you create a workflow that uses services to implement the functionality, then create an API route that executes that workflow. + In this step, you’ll create the workflow that you’ll execute when a customer purchases a subscription. The workflow accepts a cart’s ID, and it has three steps: @@ -648,6 +664,8 @@ The workflow returns the created subscription and order. ## Step 6: Override Complete Cart API Route +To expose custom commerce features to frontend applications, such as the Medusa Admin dashboard or a storefront, you expose an endpoint by creating an API route. + In this step, you’ll change what happens when the [Complete Cart API route](!api!/store#carts_postcartsidcomplete) is used to complete the customer’s purchase and place an order. Create the file `src/api/store/carts/[id]/complete/route.ts` with the following content: @@ -1076,6 +1094,8 @@ In the next section, you’ll extend the Medusa admin and use these API routes t ## Step 8: Extend Admin +The Medusa Admin is customizable, allowing you to inject widgets into existing pages or add UI routes to create new pages. + In this step, you’ll add two UI routes: 1. One to view all subscriptions. @@ -1874,6 +1894,8 @@ In the next step, you’ll execute the workflow in a scheduled job. ## Step 10: Create New Subscription Orders Scheduled Job +A scheduled job is an asynchronous function executed at a specified interval pattern. Use scheduled jobs to execute a task at a regular interval. + In this step, you’ll create a scheduled job that runs once a day. It finds all subscriptions whose `next_order_date` property is the current date and uses the workflow from the previous step to create an order for them. Create the file `src/jobs/create-subscription-orders.ts` with the following content: