docs: general fixes and overall changes (#7258)
* editing halfway * edited second half * adjust starter steps * fix build * typo fix
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
8db62827ac
commit
327e446974
57 files changed
+872
-1849
No files matched your search
File renamed without changes.
@@ -14,9 +14,11 @@ Admin customizations are coming soon.
|
||||
|
||||
## Overview
|
||||
|
||||
The Medusa Admin is installed in your Medusa application and runs at port `7001` when you start the Medusa application.
|
||||
The Medusa Admin is an admin dashboard that merchants use to manage their store's data.
|
||||
|
||||
You can extend or customize the Medusa Admin to add widgets or new pages that interact with API routes and provide admin users with custom functionalities.
|
||||
You can extend the Medusa Admin to add widgets and new pages. Your customizations interact with API routes to provide merchants with custom functionalities.
|
||||
|
||||
The Medusa Admin is installed in your Medusa application and runs at port `7001` when you start the Medusa application.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ The Medusa core application provides a set of admin and store API routes out-of-
|
||||
|
||||
An API Route is created in a TypeScript or JavaScript file under the `/src/api` directory of your Medusa application. The file’s name must be `route.ts` or `route.js`.
|
||||
|
||||
Each route file holds API Route handler functions for each HTTP method (`GET`, `POST`, `DELETE`, etc…).
|
||||
Each route file exports API Route handler functions for at least one HTTP method (`GET`, `POST`, `DELETE`, etc…).
|
||||
|
||||
For example, to create a `GET` API Route at `/store/hello-world`, create the file `src/api/store/hello-world/route.ts` with the following content:
|
||||
|
||||
@@ -54,7 +54,7 @@ curl http://localhost:9000/store/hello-world
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
## When to Use API Routes
|
||||
|
||||
<Note title="Use API routes when" type="success">
|
||||
|
||||
|
||||
@@ -45,4 +45,8 @@ export const GET = async (
|
||||
|
||||
When you resolve the `ModuleRegistrationName.PRODUCT` (or `productModuleService`) registration name, you're actually resolving the main service of the Product Module.
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
To resolve the main service of any commerce module, use the `ModuleRegistrationName` enum imported from `@medusajs/modules-sdk` to refer to its registration name in the Medusa container.
|
||||
|
||||
</Note>
|
||||
@@ -25,7 +25,7 @@ Data models are based on [MikroORM](https://mikro-orm.io/docs/quick-start). So,
|
||||
|
||||
</Note>
|
||||
|
||||
A data model is a class created in a TypeScript or JavaScript file created in a module under its `models` directory.
|
||||
A data model is a class created in a TypeScript or JavaScript file under a module's `models` directory.
|
||||
|
||||
For example, create the file `src/modules/hello/models/my-custom.ts` with the following content:
|
||||
|
||||
@@ -73,7 +73,7 @@ The `generateEntityId` utility method prefixes the `id` of a record with the str
|
||||
|
||||
After creating the data model, you must create a migration that creates a table in your database for this data model.
|
||||
|
||||
A migration is a class that implements an `up` and `down` method, where the `up` method reflects changes on the database, and the `down` method reverts the changes from the database.
|
||||
A migration is a class created in a TypeScript or JavaScript file under a module's `migrations` directory. It implements an `up` and `down` method, where the `up` method reflects changes on the database, and the `down` method reverts the changes from the database.
|
||||
|
||||
<Details summaryContent="Generate with MikroORM">
|
||||
MikroORM provides a CLI tool that helps you generate migrations. To use it:
|
||||
@@ -106,7 +106,7 @@ A migration is a class that implements an `up` and `down` method, where the `up`
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
You can add this command as a script in `package.json` for easy usage in the future. Use this command whenever you want to generate a new migration in your module.
|
||||
Add this command as a script in `package.json` for easy usage in the future. Use this command whenever you want to generate a new migration in your module.
|
||||
|
||||
</Note>
|
||||
|
||||
@@ -116,7 +116,7 @@ A migration is a class that implements an `up` and `down` method, where the `up`
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
```ts title="src/modules/migrations/Migration20240429090012.ts"
|
||||
import { Migration } from "@mikro-orm/migrations"
|
||||
|
||||
export class Migration20240429090012 extends Migration {
|
||||
@@ -142,7 +142,7 @@ The queries performed in each of the methods use PostgreSQL syntax.
|
||||
|
||||
### Add Migration to Module Definition
|
||||
|
||||
After creating the migration, you must add it to your module's definition. Otherwise, the Medusa application won't run it.
|
||||
After creating the migration, you must add it to your module's definition.
|
||||
|
||||
To add a module's migrations to its definitions, use the `ModulesSdkUtils` utility functions imported from `@medusajs/utils`. It has functions to create and define the migration scripts in your module definition.
|
||||
|
||||
@@ -213,7 +213,7 @@ If ran successfully, the `my_custom` table will be created in the database.
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
## When to Use Data Models
|
||||
|
||||
<Note title="Use data models when" type="success">
|
||||
|
||||
|
||||
@@ -39,12 +39,14 @@ export const config: SubscriberConfig = {
|
||||
|
||||
A subscriber file must export:
|
||||
|
||||
- The subscriber function which is an asynchronous function executed whenever the associated event is triggered.
|
||||
- The subscriber function that is an asynchronous function executed whenever the associated event is triggered.
|
||||
- A configuration object defining the event this subscriber is listening to.
|
||||
|
||||
The above subscriber listens to the `ProductService.Events.CREATED` (`product-created`) event. Whenever the event is emitted, it logs in the terminal `A product is created`.
|
||||
|
||||
### Test Subscriber
|
||||
{/* TODO add when we have the admin dashboard to use with V2 for easy testing. */}
|
||||
|
||||
{/* ### Test Subscriber
|
||||
|
||||
To test the subscriber, start the Medusa application:
|
||||
|
||||
@@ -59,11 +61,11 @@ info: Processing product.created which has 1 subscribers
|
||||
A product is created
|
||||
```
|
||||
|
||||
The first message indicates that the `product.created` event was emitted, and the second one is the message logged from the subscriber.
|
||||
The first message indicates that the `product.created` event was emitted, and the second one is the message logged from the subscriber. */}
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
## When to Use Subscribers
|
||||
|
||||
<Note title="Use subscribers when" type="success">
|
||||
|
||||
|
||||
@@ -10,19 +10,13 @@ In this chapter, you’ll learn about loaders and how to use them.
|
||||
|
||||
A loader is a function executed when the Medusa application starts.
|
||||
|
||||
A loader can be created either within a module or in the `src/loaders` directory.
|
||||
|
||||
<Note>
|
||||
|
||||
This guide explains the first approach. This second approach will be explained in later chapters.
|
||||
|
||||
</Note>
|
||||
A module can define loaders to execute on application start-up.
|
||||
|
||||
---
|
||||
|
||||
## How to Create a Loader?
|
||||
|
||||
A loader is created in a TypeScript or JavaScript file under the `loaders` directory of a module. The file must export the loader function.
|
||||
A loader is created in a TypeScript or JavaScript file under a module's `loaders` directory.
|
||||
|
||||
For example, create the file `src/modules/hello/loaders/hello-world.ts` with the following content:
|
||||
|
||||
@@ -36,7 +30,7 @@ export default function helloWorldLoader() {
|
||||
|
||||
### Export Loader in Module Definition
|
||||
|
||||
You must export your loaders in the module definition. Otherwise, your Medusa application won't run them.
|
||||
You must export your loaders in the module definition.
|
||||
|
||||
To do that, import the loader in `src/modules/hello/index.ts` and export it in the module's definition:
|
||||
|
||||
@@ -52,7 +46,7 @@ export default {
|
||||
}
|
||||
```
|
||||
|
||||
The value of the `loaders` property of the module definition is an array of loader functions.
|
||||
The value of the `loaders` property is an array of loader functions.
|
||||
|
||||
### Test Loader
|
||||
|
||||
@@ -70,13 +64,12 @@ Among the messages logged in the terminal, you’ll see the following message:
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
## When to Use Loaders
|
||||
|
||||
<Note title="Use loaders when" type="success">
|
||||
|
||||
- You're performing an action at application start-up.
|
||||
- You're establishing a one-time connection with an external system.
|
||||
- You're registering a custom resource in the container.
|
||||
|
||||
</Note>
|
||||
|
||||
|
||||
@@ -8,7 +8,9 @@ In this chapter, you’ll learn about Medusa’s Medusa container and how to use
|
||||
|
||||
## What is the Medusa container?
|
||||
|
||||
The Medusa container holds all registered resources in the Medusa application. You use it to resolve resources, such as services.
|
||||
The Medusa container holds all resources registered in the Medusa application. You have access to it in your customizations.
|
||||
|
||||
You use the Medusa container to resolve resources, such as services.
|
||||
|
||||
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:
|
||||
|
||||
@@ -40,4 +42,4 @@ export const GET = async (
|
||||
}
|
||||
```
|
||||
|
||||
This route handler function resolves the `IProductModuleService` and uses it to return the full count of products in the Medusa application.
|
||||
You resolve the `IProductModuleService` and uses it to return the full count of products in the Medusa application.
|
||||
@@ -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 that can be integrated into your Medusa application without affecting the overall system.
|
||||
A module is a package of reusable functionalities. It can be integrated into your Medusa application without affecting the overall system.
|
||||
|
||||
All commerce and architectural customizations and development start with creating a module.
|
||||
Use modules to customize or develop commerce and architectural features in your Medusa application.
|
||||
|
||||
---
|
||||
|
||||
@@ -24,15 +24,15 @@ All commerce and architectural customizations and development start with creatin
|
||||
|
||||
</Note>
|
||||
|
||||
Modules are created in a sub-directory of `src/modules`. The directory name is the camel-case name of the module.
|
||||
Modules are created in a sub-directory of `src/modules`.
|
||||
|
||||
For example, create the directory `src/modules/hello`.
|
||||
|
||||
### 1. Create a Service
|
||||
|
||||
A module must defines a service. A service is a TypeScript or JavaScript class holding methods related to a business logic or commerce functionality.
|
||||
A module must define a service. A service is a TypeScript or JavaScript class holding methods related to a business logic or commerce functionality.
|
||||
|
||||
For example, create the service `src/modules/hello/service.ts` with the following content:
|
||||
For example, create the file `src/modules/hello/service.ts` with the following content:
|
||||
|
||||
```ts title="src/modules/hello/service.ts"
|
||||
export default class HelloModuleService {
|
||||
@@ -42,8 +42,6 @@ export default class HelloModuleService {
|
||||
}
|
||||
```
|
||||
|
||||
When the module is loaded in the Medusa application, its main service is registered in the Medusa container.
|
||||
|
||||
### 2. Export Module Definition
|
||||
|
||||
A module must have an `index.ts` file in its root directory that exports its definition. The definition specifies the main service of the module.
|
||||
@@ -58,9 +56,9 @@ export default {
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Register Module in Configurations
|
||||
### 3. Add Module to Configurations
|
||||
|
||||
The last step is to register the module in Medusa’s configurations.
|
||||
The last step is to add the module in Medusa’s configurations.
|
||||
|
||||
In `medusa-config.js`, add the module to the `modules` object:
|
||||
|
||||
@@ -73,11 +71,13 @@ const modules = {
|
||||
}
|
||||
```
|
||||
|
||||
The key (`helloModuleService`) is the name of the module’s main service to be registered in the Medusa container. Its value is an object having the `resolve` property. `resolve` ’s value is either an `npm` package’s name or a path to the directory holding the module.
|
||||
Its key (`helloModuleService`) is the name of the module’s main service. It will be registered in the Medusa container with that name.
|
||||
|
||||
Its value is an object having the `resolve` property, whose value is either a path to the directory holding the module or an `npm` package’s name.
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
When `resolve` points to a directory, it must point to the transpiled module (the directory the module is in after running the `build` command). Hence, the path in the example above points to the module in the `dist` directory.
|
||||
When you run the `build` or `dev` command, your customizations are transpiled from the `src` directory into the `dist` directory. So, you point to the module in the `dist` directory.
|
||||
|
||||
</Note>
|
||||
|
||||
@@ -129,10 +129,10 @@ You’ll receive the following response:
|
||||
|
||||
## When to Use Modules
|
||||
|
||||
Use a module when you're implementing custom business logic or extending existing ones.
|
||||
|
||||
Some common use cases of when a module is useful:
|
||||
<Note title="Use modules when" type="success">
|
||||
|
||||
- You're implementing a custom commerce feature. For example, you're implementing digital products.
|
||||
- You want to extend data models in other commerce modules, such as adding a field or a relation to the `Product` model.
|
||||
- You want to re-use your custom commerce functionalities across Medusa applications or use them in other environments, such as Edge functions and Next.js apps.
|
||||
|
||||
</Note>
|
||||
@@ -10,13 +10,13 @@ In this document, you'll learn about the expected files and directories in your
|
||||
|
||||
## index.ts
|
||||
|
||||
The `index.ts` file in the root of your module's directory is the only required file. It must export the module's definition as explained in the [previous chapter](../modules-and-services/page.mdx).
|
||||
The `index.ts` file in the root of your module's directory is the only required file. It must export the module's definition as explained in a [previous chapter](../modules-and-services/page.mdx).
|
||||
|
||||
---
|
||||
|
||||
## service.ts
|
||||
|
||||
A module must have a main service created in the `service.ts` file at the root of your module directory as explained in the [previous chapter](../modules-and-services/page.mdx).
|
||||
A module must have a main service. It's created in the `service.ts` file at the root of your module directory as explained in a [previous chapter](../modules-and-services/page.mdx).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -11,10 +11,8 @@ By the end of these chapter, you’ll be able to:
|
||||
- Expose your custom functionalities through REST APIs.
|
||||
- Create custom modules that define custom business logic.
|
||||
- Create custom data models.
|
||||
- Perform asynchronus actions when an event occurs.
|
||||
- Execute scripts when the Medusa application starts.
|
||||
- Create scheduled jobs that run at a specified pattern during the Medusa application's runtime.
|
||||
- Create flows as a series of steps involving multiple services.
|
||||
- Perform asynchronus actions when an event occurs.
|
||||
- Run tasks at a specified time or pattern during the Medusa application's runtime.
|
||||
- Create custom flows as a series of steps involving multiple services.
|
||||
- Customize the admin dashboard to inject components on existing pages or add new pages.
|
||||
|
||||
You'll then use this knowledge to learn more about Medusa's modular architecture, and how to make customizations to core models and features.
|
||||
@@ -6,9 +6,15 @@ export const metadata = {
|
||||
|
||||
In this chapter, you’ll learn about scheduled jobs and how to use them.
|
||||
|
||||
<Note type="soon">
|
||||
|
||||
Scheduled jobs are coming soon.
|
||||
|
||||
</Note>
|
||||
|
||||
## What is a Scheduled Job?
|
||||
|
||||
A scheduled job is a function that is executed at a specified interval of time in the background of your Medusa application. It’s like a cron job that runs during the application's runtime.
|
||||
A scheduled job is a function executed at a specified interval of time in the background of your Medusa application. It’s like a cron job that runs during the application's runtime.
|
||||
|
||||
For example, you can synchronize your inventory with an Enterprise Resource Planning (ERP) system once a day using a scheduled job.
|
||||
|
||||
@@ -44,7 +50,7 @@ export const config: ScheduledJobConfig = {
|
||||
|
||||
A scheduled job file must export:
|
||||
|
||||
- The function executed whenever it’s time to run the scheduled job.
|
||||
- The function to be executed whenever it’s time to run the scheduled job.
|
||||
- A configuration object defining the job. It has two properties:
|
||||
- `name`: a unique name for the job.
|
||||
- `schedule`: a [cron expression](https://crontab.guru/).
|
||||
@@ -82,7 +88,7 @@ The first line indicates that the application is executing the scheduled job. Th
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
## When to Use Scheduled Jobs
|
||||
|
||||
<Note title="Use scheduled jobs when" type="success">
|
||||
|
||||
@@ -93,7 +99,7 @@ The first line indicates that the application is executing the scheduled job. Th
|
||||
|
||||
<Note title="Don't use scheduled jobs if" type="error">
|
||||
|
||||
- You want the action to execute at a specified time interval while the Medusa application isn't running. Instead, use the operating system's equivalent of a cron job.
|
||||
- You want the action to execute at a specified time interval while the Medusa application **isn't** running. Instead, use the operating system's equivalent of a cron job.
|
||||
- You want to execute the action once. Use loaders instead.
|
||||
- You want to execute the action if an event occurs. Use subscribers instead.
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ 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 Medusa 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, if necessary, 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. This makes it possible to keep track of your Workflow’s progress, automatically retry failing steps, and roll back steps.
|
||||
|
||||
---
|
||||
|
||||
@@ -20,7 +20,7 @@ You construct a Workflow similar to how you create a JavaScript function, but un
|
||||
|
||||
### 1. Create the Steps
|
||||
|
||||
A workflow is made of a series of steps. A step is created using the `createStep` utility function.
|
||||
A workflow is made of a series of steps. A step is created using the `createStep` utility function imported from `@medusajs/workflows-sdk`.
|
||||
|
||||
Create the file `src/workflows/hello-world.ts` with the following content:
|
||||
|
||||
@@ -89,13 +89,13 @@ This creates a `hello-world` workflow. When you create a workflow, it’s constr
|
||||
|
||||
### 3. Execute the Workflow
|
||||
|
||||
You can execute a workflow from different places within Medusa.
|
||||
You can execute a workflow from different resources within Medusa.
|
||||
|
||||
- Use API Routes to execute the workflow in response to an API request or a webhook.
|
||||
- Use Subscribers to execute a workflow when an event is triggered.
|
||||
- Use Scheduled Jobs to execute a workflow on a regular schedule.
|
||||
- Use API routes to execute the workflow in response to an API request or a webhook.
|
||||
- Use subscribers to execute a workflow when an event is triggered.
|
||||
- Use scheduled jobs to execute a workflow on a regular schedule.
|
||||
|
||||
To execute the workflow, invoke it passing the Medusa container as a parameter, then use its run method:
|
||||
To execute the workflow, invoke it passing the Medusa container as a parameter. Then, use its `run` method:
|
||||
|
||||
<CodeTabs group="resource-types">
|
||||
<CodeTab label="API Route" value="api-route">
|
||||
@@ -195,7 +195,7 @@ npm run dev
|
||||
|
||||
Then, send a `GET` request to `/store/workflow`:
|
||||
|
||||
```bash apiTesting testApiMethod="GET" testApiUrl="http://localhost:9000/store/workflows"
|
||||
```bash apiTesting testApiMethod="GET" testApiUrl="http://localhost:9000/store/workflow"
|
||||
curl http://localhost:9000/store/workflow
|
||||
```
|
||||
|
||||
@@ -209,7 +209,7 @@ You’ll receive the following response:
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
## When to Use Workflows
|
||||
|
||||
<Note title="Use workflows when" type="success">
|
||||
|
||||
@@ -223,7 +223,7 @@ You’ll receive the following response:
|
||||
|
||||
## Resolve Resources
|
||||
|
||||
Each step in the workflow receives as a second parameter a `context` object. The object holds a `container` property which is the Medusa container. You can use it to resolve other resources, such as services, of your Medusa application.
|
||||
Each step in the workflow receives as a second parameter a `context` object. The object holds a `container` property which is the Medusa container. Use it to resolve other resources, such as services, of your Medusa application.
|
||||
|
||||
For example:
|
||||
|
||||
|
||||
Reference in new issue
Block a user