asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: added loaders documentation (#4019)

Browse Source 
* docs: added loaders documentation

* added a link to the loaders documentation
This commit is contained in:
Shahed Nasser
2023-05-04 18:55:50 +03:00
committed by GitHub
parent 7fd22ecb4d
commit e046aa17db
17 changed files with 254 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/content/development/batch-jobs/index.mdx
View File

@@ -71,7 +71,7 @@ If the batch job fails at any point in this flow, its status is changed to `fail
## Custom Development
Developers can create custom batch jobs in the Medusa backend, a plugin, or in a Commerce Module. Developers can also customize existing batch job strategies in the core, such as the import strategy.
Developers can create custom batch jobs in the Medusa backend, a plugin, or in a module. Developers can also customize existing batch job strategies in the core, such as the import strategy.
<DocCardList colSize={6} items={[
{

6
docs/content/development/endpoints/overview.mdx
View File

@@ -15,9 +15,9 @@ The Medusa Backend is a web server built on top of [Express](https://expressjs.c
Endpoints are REST APIs that allow a frontend or an external system to interact with the Medusa Backend to retrieve and process data, or perform business logic. Endpoints are [Express routes](https://expressjs.com/en/starter/basic-routing.html).
Each [Commerce Module](../../modules/overview.mdx) contains a set of endpoints specific to the functionalities that it provides. Since the core package that powers the Medusa Backend acts as an orchestrator of Commerce Modules and exposes their endpoints, the endpoints of each of these Commerce Modules are available within the Medusa Backend.
Each [commerce module](../../modules/overview.mdx) contains a set of endpoints specific to the functionalities that it provides. Since the core package that powers the Medusa Backend acts as an orchestrator of commerce modules and exposes their endpoints, the endpoints of each of these commerce modules are available within the Medusa Backend.
The Commerce Modules provide two types of endpoints: Store APIs and Admin APIs. The Store APIs are typically accessed from the storefront. For example, you can use the Store APIs to show customers available products or implement a cart and checkout flow.
The commerce modules provide two types of endpoints: Store APIs and Admin APIs. The Store APIs are typically accessed from the storefront. For example, you can use the Store APIs to show customers available products or implement a cart and checkout flow.
The Admin APIs are typically accessed from an admin dashboard. For example, you can use the Admin APIs to allow admins to manage the store’s data such as products, orders, and so on.
@@ -46,7 +46,7 @@ The Admin APIs are typically accessed from an admin dashboard. For example, you
## Custom Development
Aside from using the endpoints that Commerce Modules, developers can create their own REST APIs either directly in the Medusa Backend, in a plugin, or in a custom Commerce Module.
Aside from using the endpoints that commerce modules, developers can create their own REST APIs either directly in the Medusa Backend, in a plugin, or in a custom commerce module.
:::tip

2
docs/content/development/entities/migrations/overview.mdx
View File

@@ -61,7 +61,7 @@ This will use the underlying `seed` command provided by Medusa's CLI to seed you
## Custom Development
Developers can create custom entities in the Medusa backend, a plugin, or in a Commerce Module, then ensure it reflects in the database using a migration.
Developers can create custom entities in the Medusa backend, a plugin, or in a module, then ensure it reflects in the database using a migration.
<DocCardList colSize={6} items={[
{

2
docs/content/development/entities/overview.mdx
View File

@@ -70,7 +70,7 @@ If you want to remove a property from the `metadata` object, you can pass the `m
## Custom Development
Developers can create custom entities in the Medusa backend, a plugin, or in a Commerce Module, then ensure it reflects in the database using a migration.
Developers can create custom entities in the Medusa backend, a plugin, or in a module, then ensure it reflects in the database using a migration.
<DocCardList colSize={6} items={[
{

2
docs/content/development/events/subscribers.mdx
View File

@@ -31,7 +31,7 @@ Subscribers are useful in many use cases, including:
## Custom Development
Developers can create custom subscribers in the Medusa backend, a plugin, or in a Commerce Module.
Developers can create custom subscribers in the Medusa backend, a plugin, or in a module.
<DocCard item={{
type: 'link',

2
docs/content/development/file-service/overview.mdx
View File

@@ -21,7 +21,7 @@ A file service is a TypeScript or JavaScript class that extends the `AbstractFil
## Custom Development
Developers can create a custom file service with the desired functionality directly within the Medusa Core, in a plugin, or in a Commerce Module.
Developers can create a custom file service with the desired functionality directly within the Medusa Core, in a plugin, or in a module.
<DocCard item={{
type: 'link',

86
docs/content/development/loaders/create.md Normal file
View File

@@ -0,0 +1,86 @@
---
description: 'Learn how to create a loader in Medusa. A loader can be created in the Medusa backend codebase, in a plugin, or in a module.'
addHowToData: true
---
# How to Create a Loader
In this document, you’ll learn how to create a loader in Medusa. A loader can be created in the Medusa backend codebase, in a plugin, or in a module.
## Step 1: Create Loader File
Create a TypeScript or JavaScript file in the `src/loaders` directory that will hold your custom script. There are no restrictions on the name of the file.
For example, create the file `src/loaders/my-loader.ts` that will hold the loader.
---
## Step 2: Define the Loader
The loader file must export a function.
### Parameters of Loaders in Medusa Backend and Plugins
When the loader is defined in the Medusa backend or a plugin, the function receives the following parameters:
1. `container`: the first parameter, which is a `AwilixContainer` object. You can use the container to register custom resources into the dependency container or resolve resources from the dependency container.
2. `config`: the second parameter, which is an object that holds the loader’s plugin options. If the loader is not created inside a plugin, the config object will be empty.
### Parameters of Loaders in Modules
When the loader is defined in a module, it receives the following parameters:
1. `container`: the first parameter, which is a `AwilixContainer` object. You can use the container to register custom resources into the dependency container or resolve resources from the dependency container.
2. `logger`: the second parameter, which is a `Logger` object. The logger can be used to log messages in the console.
3. `config`: the third parameter, which is an object that holds the loader’s module options.
### Example Implementation
For example, this loader function resolves the `ProductService` and logs in the console the count of products in the Medusa backend:
```ts title=src/loaders/my-loader.ts
import { ProductService } from "@medusajs/medusa"
import { AwilixContainer } from "awilix"
export default async (
container: AwilixContainer,
config: Record<string, unknown>
): Promise<void> => {
console.info("Starting loader...")
const productService = container.resolve<ProductService>(
"productService"
)
console.info(`Products count: ${
await productService.count()
}`)
console.info("Ending loader...")
}
```
---
## Step 3: Run Build Command
In the directory of your project, run the following command to transpile the files from the `src` to the `dist` directory:
```bash npm2yarn
npm run build
```
---
## Test it Out
:::note
This section explains how to test out the loader if it’s created in the Medusa backend codebase. If you’re creating your loader in a plugin, you can learn how to test it in the [plugins documentation](../plugins/create.md#test-your-plugin). Alternatively, if you’re creating your loader in a module, you can learn how to test it in the [modules documentation](../modules/create.mdx#step-4-test-your-module).
:::
Run the following command to start the Medusa backend:
```bash npm2yarn
npm run start
```
Your loader script should run on the Medusa backend startup. If you logged a message in the console, similar to the example above, you should see it in the console.

69
docs/content/development/loaders/overview.mdx Normal file
View File

@@ -0,0 +1,69 @@
---
description: "earn what loaders are in Medusa. A loader is a script that runs when the Medusa backend starts."
---
import DocCard from '@theme/DocCard';
import Icons from '@theme/Icon';
# Loaders
In this document, you’ll learn what loaders are in Medusa.
## Overview
A loader is a script that runs when the Medusa backend starts. The Medusa backend uses loaders to initialize the database connection, load plugins, register resources in the dependency container, and more.
Loaders can be created within the Medusa backend codebase, in a plugin, or in a module to perform custom actions when the backend starts. The loader is created in a TypeScript or JavaScript file located in the `src/loaders` directory, then transpiled using the `build` command into the `dist/loaders` directory.
### Loader Examples
For example, the Redis Event Bus module uses a loader to establish a connection with Redis and log a message in the console.
Another example is the Algolia plugin, which uses a loader to update the index settings when the Medusa backend starts based on the plugin’s options.
Loaders can be used to access the dependency container and register custom resources in it.
Loaders can also be used to create [scheduled jobs](../scheduled-jobs/overview.mdx) that run at a specified interval of time. For example:
```ts
const publishJob = async (container, options) => {
const jobSchedulerService =
container.resolve("jobSchedulerService")
jobSchedulerService.create(
"publish-products",
{},
"0 0 * * *",
async () => {
// job to execute
const productService = container.resolve("productService")
const draftProducts = await productService.list({
status: "draft",
})
for (const product of draftProducts) {
await productService.update(product.id, {
status: "published",
})
}
}
)
}
export default publishJob
```
---
## Custom Development
Developers can create a loader with the desired functionality directly within the Medusa Core, in a plugin, or in a module.
<DocCard item={{
type: 'link',
href: '/development/loaders/create',
label: 'Create a Loader',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to create a loader.'
}
}} />

2
docs/content/development/modules/create.mdx
View File

@@ -139,7 +139,7 @@ All property types such as `ModuleLoaderFunction` can be loaded from the `@medus
Where:
- `service`: This is the only required property to be exported. It should be the main service your module exposes, and it must implement all the declared methods on the module interface. For example, if it's a cache module, it must implement the `ICacheService` interface exported from `@medusajs/types`.
- `loaders`: (optional) an array of functions used to perform an action while loading the module. For example, you can log a message that the module has been loaded, or if your module's scope is [isolated](#module-scope) you can use the loader to establish a database connection.
- `loaders`: (optional) an array of [loader](../loaders/overview.mdx) functions used to perform an action while loading the module. For example, you can log a message that the module has been loaded, or if your module's scope is [isolated](#module-scope) you can use the loader to establish a database connection.
- `migrations`: (optional) an array of objects containing database migrations that should run when the `migration` command is used with Medusa's CLI.
- `models`: (optional) an array of entities that your module creates.
- `runMigrations`: (optional) a function that can be used to define migrations to run when the `migration run` command is used with Medusa's CLI. The migrations will only run if they haven't already. This will only be executed if the module's scope is [isolated](#module-scope).

2
docs/content/development/modules/overview.mdx
View File

@@ -13,7 +13,7 @@ In this document, you’ll learn what Modules are and how can you use them durin
Modules are self-contained, reusable pieces of code that encapsulate specific functionality or features within an ecommerce application. They foster separation of concerns, maintainability, and reusability by organizing code into smaller, independent units that can be easily managed, tested, and integrated with other modules.
Modules further increase Medusa’s extensibility. Commerce modules, such as the cart engine, can be extended or entirely replaced with your own custom logic. They can also run independently of the core Medusa package, allowing you to utilize the commerce module within a larger commerce ecosystem. For example, you can use the Order module as an Order Management System (OMS) without using Medusa’s core.
Modules further increase Medusa’s extensibility. commerce modules, such as the cart engine, can be extended or entirely replaced with your own custom logic. They can also run independently of the core Medusa package, allowing you to utilize the commerce module within a larger commerce ecosystem. For example, you can use the Order module as an Order Management System (OMS) without using Medusa’s core.
This also applies to core logic such as caching or events systems. You can use modules to integrate any logic or third-party service to handle this logic. This gives you greater flexibility in how you choose your tech stack.

2
docs/content/development/notification/overview.mdx
View File

@@ -95,7 +95,7 @@ An example of a flow that can be implemented using Medusa's Notification API is
## Custom Development
Developers can create custom notification providers in the Medusa backend, a plugin, or in a Commerce Module.
Developers can create custom notification providers in the Medusa backend, a plugin, or in a module.
<DocCard item={{
type: 'link',

10
docs/content/development/overview.mdx
View File

@@ -18,7 +18,7 @@ Other ecommerce platforms offer a finite set of features accessible through an A
Medusa's building blocks ship as NPM packages of the following types:
- [Commerce Modules](../modules/overview.mdx), which are isolated commerce logic for different domains. For example, an Inventory Module.
- [Commerce modules](../modules/overview.mdx), which are isolated commerce logic for different domains. For example, an Inventory Module.
- A core package responsible for orchestrating the different commerce modules and exposing REST APIs.
---
@@ -164,7 +164,7 @@ To better understand how you can use Medusa, here are some common use cases that
### Ecommerce Building Blocks
Developers can set up the core package and handpick the Commerce Modules they want to use. This gives them great flexibility in choosing the features they want to provide in their ecommerce store, while utilizing the powerful architecture in the core package.
Developers can set up the core package and handpick the commerce modules they want to use. This gives them great flexibility in choosing the features they want to provide in their ecommerce store, while utilizing the powerful architecture in the core package.
![Ecommerce Building Blocks](https://res.cloudinary.com/dza7lstvk/image/upload/v1678954316/Medusa%20Docs/Diagrams/ecommerce-building-blocks_llgnn2.jpg)
@@ -172,11 +172,11 @@ Developers can modify and tailor the modules that Medusa offers to their use cas
### Medusa in Microservices Architectures
Medusa’s Commerce Modules can be used in isolation from the core package and within a larger ecosystem. For example, you can use Medusa’s Cart module within a blog to allow readers to buy merch.
Medusa’s commerce modules can be used in isolation from the core package and within a larger ecosystem. For example, you can use Medusa’s Cart module within a blog to allow readers to buy merch.
![Medusa in Microservices Architecture](https://res.cloudinary.com/dza7lstvk/image/upload/v1678954316/Medusa%20Docs/Diagrams/microservices-architecture-use-case_vubgno.jpg)
Developers can benefit from Medusa’s Modules that provide essential ecommerce features while maintaining the ecommerce ecosystem of their choice. Commerce Modules can be installed in your setup as NPM packages.
Developers can benefit from Medusa’s Modules that provide essential ecommerce features while maintaining the ecommerce ecosystem of their choice. Commerce modules can be installed in your setup as NPM packages.
### Vertical Ecommerce Platforms
@@ -186,7 +186,7 @@ Developers can use Medusa to build a vertical ecommerce platform as it provides
### Out-of-Box APIs
Since Medusa’s Commerce Modules are NPM packages, they can be installed and used in any JavaScript project.
Since Medusa’s commerce modules are NPM packages, they can be installed and used in any JavaScript project.
By installing a Module in your project and expose its APIs based on the framework you’re using, you can get ecommerce REST APIs right from your frontend framework without having to create a separate project.

2
docs/content/development/scheduled-jobs/create.md
View File

@@ -25,7 +25,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no
## 1. Create a File
Each scheduled job should reside in a TypeScript or JavaScript file under the `src/loaders` directory.
Each scheduled job should reside in a [loader](../loaders/overview.mdx), which is a TypeScript or JavaScript file located under the `src/loaders` directory.
Start by creating the `src/loaders` directory. Then, inside that directory, create the JavaScript or TypeScript file that you’ll add the scheduled job in. You can use any name for the file.

2
docs/content/development/scheduled-jobs/overview.mdx
View File

@@ -27,7 +27,7 @@ Future versions of Medusa will allow switching out Redis and using a different p
## Custom Development
Developers can create an unlimited number of scheduled jobs within the Medusa Backend, a plugin, or a custom Commerce Module.
Developers can create an unlimited number of scheduled jobs within the Medusa Backend, a plugin, or a custom module.
<DocCard item={{
type: 'link',

2
docs/content/development/search/overview.mdx
View File

@@ -31,7 +31,7 @@ If you create your own search service in the Medusa backend codebase, it will be
## Custom Development
Developers can create a custom search service with the desired functionality or third-party integration either directly within the Medusa Core, in a plugin, or in a Commerce Module.
Developers can create a custom search service with the desired functionality or third-party integration either directly within the Medusa Core, in a plugin, or in a module.
<DocCard item={{
type: 'link',

2
docs/content/development/services/overview.mdx
View File

@@ -39,7 +39,7 @@ If you're creating a service in a plugin, learn more about the required structur
## Custom Development
Developers can create custom services in the Medusa backend, a plugin, or in a Commerce Module.
Developers can create custom services in the Medusa backend, a plugin, or in a module.
<DocCardList colSize={6} items={[
{

135
www/docs/sidebars.js
View File

@@ -1398,34 +1398,6 @@ module.exports = {
},
],
},
{
type: "category",
label: "Modules",
items: [
{
type: "doc",
id: "development/modules/overview",
label: "Overview",
},
{
type: "html",
value: "How-to",
customProps: {
sidebar_is_group_divider: true,
},
},
{
type: "doc",
id: "development/modules/create",
label: "Create a Module",
},
{
type: "doc",
id: "development/modules/publish",
label: "Publish a Module",
},
],
},
{
type: "category",
label: "Events",
@@ -1481,6 +1453,29 @@ module.exports = {
},
],
},
{
type: "category",
label: "Loaders",
items: [
{
type: "doc",
id: "development/loaders/overview",
label: "Overview",
},
{
type: "html",
value: "How-to",
customProps: {
sidebar_is_group_divider: true,
},
},
{
type: "doc",
id: "development/loaders/create",
label: "Create a Loader",
},
],
},
{
type: "category",
label: "Scheduled Jobs",
@@ -1504,6 +1499,34 @@ module.exports = {
},
],
},
{
type: "category",
label: "Modules",
items: [
{
type: "doc",
id: "development/modules/overview",
label: "Overview",
},
{
type: "html",
value: "How-to",
customProps: {
sidebar_is_group_divider: true,
},
},
{
type: "doc",
id: "development/modules/create",
label: "Create a Module",
},
{
type: "doc",
id: "development/modules/publish",
label: "Publish a Module",
},
],
},
{
type: "category",
label: "Plugins",
@@ -1532,34 +1555,6 @@ module.exports = {
},
],
},
{
type: "category",
label: "Publishable API Keys",
items: [
{
type: "doc",
id: "development/publishable-api-keys/index",
label: "Overview",
},
{
type: "html",
value: "How-to",
customProps: {
sidebar_is_group_divider: true,
},
},
{
type: "doc",
id: "development/publishable-api-keys/admin/manage-publishable-api-keys",
label: "Admin: Manage Publishable API Keys",
},
{
type: "doc",
id: "development/publishable-api-keys/storefront/use-in-requests",
label: "Storefront: Use in Requests",
},
],
},
],
},
{
@@ -1610,6 +1605,34 @@ module.exports = {
},
],
},
{
type: "category",
label: "Publishable API Keys",
items: [
{
type: "doc",
id: "development/publishable-api-keys/index",
label: "Overview",
},
{
type: "html",
value: "How-to",
customProps: {
sidebar_is_group_divider: true,
},
},
{
type: "doc",
id: "development/publishable-api-keys/admin/manage-publishable-api-keys",
label: "Admin: Manage Publishable API Keys",
},
{
type: "doc",
id: "development/publishable-api-keys/storefront/use-in-requests",
label: "Storefront: Use in Requests",
},
],
},
{
type: "category",
label: "Notifications",