docs: document module providers in plugins (#11360)

* docs: document module providers in plugins * small fixes * add missing title
2025-02-07 14:17:14 +02:00
parent acc1e8e262
commit 5c44811cb0
14 changed files with 9950 additions and 9663 deletions
@@ -40,6 +40,7 @@ After the installation is done, the plugin structure will look like this:
 - `src/jobs`: Contains [scheduled jobs](../../scheduled-jobs/page.mdx).
 - `src/links`: Contains [module links](../../module-links/page.mdx).
 - `src/modules`: Contains [modules](../../modules/page.mdx).
+- `src/provider`: Contains [module providers](#create-module-providers).
 - `src/subscribers`: Contains [subscribers](../../events-and-subscribers/page.mdx).
 - `src/workflows`: Contains [workflows](../../workflows/page.mdx). You can also add [hooks](../../workflows/add-workflow-hook/page.mdx) under `src/workflows/hooks`.
 - `package.json`: Contains the plugin's package information, including general information and dependencies.
@@ -260,6 +261,112 @@ This command generates migrations for all modules in the plugin. You can then ru
 npx medusa db:migrate
 ```

+### Importing Module Resources
+
+Your plugin project should have the following exports in `package.json`:
+
+```json title="package.json"
+{
+  "exports": {
+    "./package.json": "./package.json",
+    "./workflows": "./.medusa/server/src/workflows/index.js",
+    "./modules/*": "./.medusa/server/src/modules/*/index.js",
+    "./providers/*": "./.medusa/server/src/providers/*/index.js",
+    "./*": "./.medusa/server/src/*.js"
+  }
+}
+```
+
+<Note title="Tip">
+
+Aside from the `./package.json` and `./providers`, these exports are only a recommendation. You can cherry-pick the files and directories you want to export.
+
+</Note>
+
+The plugin exports the following files and directories:
+
+- `./package.json`: The package.json file. Medusa needs to access the `package.json` when registering the plugin.
+- `./workflows`: The workflows exported in `./src/workflows/index.ts`.
+- `./modules/*`: The definition file of modules. This is useful if you create links to the plugin's modules in the Medusa application.
+- `./providers/*`: The definition file of module providers. This allows you to register the plugin's providers in the Medusa application.
+- `./*`: Any other files in the plugin's `src` directory.
+
+With these exports, you can import the plugin's resources in the Medusa application's code like this:
+
+<Note title="Tip">
+
+`@myorg/plugin-name` is the plugin package's name.
+
+</Note>
+
+```ts
+import { Workflow1, Workflow2 } from "@myorg/plugin-name/workflows"
+import BlogModule from "@myorg/plugin-name/modules/blog"
+// import other files created in plugin like ./src/types/blog.ts
+import BlogType from "@myorg/plugin-name/types/blog"
+```
+
+And you can register a module provider in the Medusa application's `medusa-config.ts` like this:
+
+```ts highlights={[["9"]]} title="medusa-config.ts"
+module.exports = defineConfig({
+  // ...
+  modules: [
+    {
+      resolve: "@medusajs/medusa/notification",
+      options: {
+        providers: [
+          {
+            resolve: "@myorg/plugin-name/providers/my-notification",
+            id: "my-notification",
+            options: {
+              channels: ["email"],
+              // provider options...
+            },
+          },
+        ],
+      },
+    },
+  ],
+})
+```
+
+You pass to `resolve` the path to the provider relative to the plugin package. So, in this example, the `my-notification` provider is located in `./src/providers/my-notification/index.ts` of the plugin.
+
+### Create Module Providers
+
+To learn how to create module providers, refer to the following guides:
+
+<CardList
+  items={[
+    {
+      title: "File Module Provider",
+      href: "!resources!/references/file-provider-module",
+    },
+    {
+      title: "Notification Module Provider",
+      href: "!resources!/references/notification-provider-module",
+    },
+    {
+      title: "Auth Module Provider",
+      href: "!resources!/references/auth/provider",
+    },
+    {
+      title: "Payment Module Provider",
+      href: "!resources!/references/payment/provider",
+    },
+    {
+      title: "Fulfillment Module Provider",
+      href: "!resources!/references/fulfillment/provider",
+    },
+    {
+      title: "Tax Module Provider",
+      href: "!resources!/references/tax/provider",
+    },
+  ]}
+  className="mb-1.5"
+/>
+
 ---

 ## 5. Publish Plugin to NPM
@@ -111,7 +111,7 @@ export const generatedEditDates = {
  "app/learn/fundamentals/module-links/link/page.mdx": "2025-01-06T09:27:25.604Z",
  "app/learn/conventions/ts-aliases/page.mdx": "2025-01-23T15:01:15.403Z",
  "app/learn/fundamentals/workflows/store-executions/page.mdx": "2025-01-27T08:45:19.028Z",
-  "app/learn/fundamentals/plugins/create/page.mdx": "2025-01-31T13:17:48.052Z",
+  "app/learn/fundamentals/plugins/create/page.mdx": "2025-02-07T10:26:53.059Z",
  "app/learn/fundamentals/plugins/page.mdx": "2025-01-22T10:14:10.433Z",
  "app/learn/customization/reuse-customizations/page.mdx": "2025-01-22T10:01:57.665Z",
  "app/learn/update/page.mdx": "2025-01-27T08:45:19.030Z",
@@ -556,7 +556,7 @@ export const generatedEditDates = {
  "references/types/NotificationTypes/interfaces/types.NotificationTypes.Attachment/page.mdx": "2024-12-17T16:57:21.128Z",
  "references/modules/fulfillment_models/page.mdx": "2024-12-23T12:30:31.974Z",
  "references/modules/order_models/page.mdx": "2025-01-27T11:43:58.772Z",
-  "references/notification/classes/notification.AbstractNotificationProviderService/page.mdx": "2024-12-17T16:57:27.196Z",
+  "references/notification/classes/notification.AbstractNotificationProviderService/page.mdx": "2025-02-07T10:35:24.483Z",
  "references/order/interfaces/order.IOrderModuleService/page.mdx": "2024-12-04T18:29:33.901Z",
  "references/types/HttpTypes/interfaces/types.HttpTypes.AdminCampaignResponse/page.mdx": "2024-12-09T13:21:33.353Z",
  "references/types/HttpTypes/interfaces/types.HttpTypes.AdminProductCategory/page.mdx": "2025-01-13T17:30:28.282Z",
@@ -848,7 +848,7 @@ export const generatedEditDates = {
  "references/auth/IAuthModuleService/methods/auth.IAuthModuleService.authenticate/page.mdx": "2025-01-07T12:54:18.941Z",
  "references/auth/IAuthModuleService/methods/auth.IAuthModuleService.validateCallback/page.mdx": "2025-01-07T12:54:18.948Z",
  "references/auth/interfaces/auth.AuthenticationResponse/page.mdx": "2024-12-09T13:21:36.233Z",
-  "references/auth_provider/classes/auth_provider.AbstractAuthModuleProvider/page.mdx": "2025-01-07T12:54:26.716Z",
+  "references/auth_provider/classes/auth_provider.AbstractAuthModuleProvider/page.mdx": "2025-02-07T10:35:24.400Z",
  "references/core_flows/Invite/Workflows_Invite/functions/core_flows.Invite.Workflows_Invite.refreshInviteTokensWorkflow/page.mdx": "2025-01-27T11:43:49.112Z",
  "references/types/CommonTypes/types/types.CommonTypes.BatchMethodResponse/page.mdx": "2024-12-09T13:21:32.849Z",
  "references/types/HttpTypes/interfaces/types.HttpTypes.AdminAddReturnShipping/page.mdx": "2024-12-09T13:21:34.545Z",
@@ -1164,7 +1164,7 @@ export const generatedEditDates = {
  "references/dml/entity/classes/dml.entity.DmlEntity/page.mdx": "2025-01-13T18:05:57.749Z",
  "references/dml/entity_builder/EntityBuilder/methods/dml.entity_builder.EntityBuilder.define/page.mdx": "2025-01-13T18:05:57.746Z",
  "references/dml/entity_builder/types/dml.entity_builder.ManyToManyOptions/page.mdx": "2025-01-13T18:05:57.744Z",
-  "references/file/classes/file.AbstractFileProviderService/page.mdx": "2024-12-09T13:21:55.512Z",
+  "references/file/classes/file.AbstractFileProviderService/page.mdx": "2025-02-07T10:35:24.403Z",
  "references/fulfillment/IFulfillmentModuleService/methods/fulfillment.IFulfillmentModuleService.createFulfillmentSets/page.mdx": "2024-12-09T13:21:55.940Z",
  "references/fulfillment/IFulfillmentModuleService/methods/fulfillment.IFulfillmentModuleService.createGeoZones/page.mdx": "2025-01-13T18:05:53.686Z",
  "references/fulfillment/IFulfillmentModuleService/methods/fulfillment.IFulfillmentModuleService.createServiceZones/page.mdx": "2024-12-09T13:21:55.976Z",
@@ -1226,7 +1226,7 @@ export const generatedEditDates = {
  "references/fulfillment/interfaces/fulfillment.OrderLineItemDTO/page.mdx": "2024-12-23T13:57:04.802Z",
  "references/fulfillment/interfaces/fulfillment.OrderLineItemTaxLineDTO/page.mdx": "2024-12-23T13:57:04.793Z",
  "references/fulfillment/types/fulfillment.JoinerRelationship/page.mdx": "2024-12-09T13:21:56.268Z",
-  "references/fulfillment_provider/classes/fulfillment_provider.AbstractFulfillmentProviderService/page.mdx": "2025-01-17T16:43:30.706Z",
+  "references/fulfillment_provider/classes/fulfillment_provider.AbstractFulfillmentProviderService/page.mdx": "2025-02-07T10:35:24.414Z",
  "references/inventory_next/IInventoryService/methods/inventory_next.IInventoryService.adjustInventory/page.mdx": "2024-12-09T13:21:56.800Z",
  "references/inventory_next/IInventoryService/methods/inventory_next.IInventoryService.confirmInventory/page.mdx": "2024-12-09T13:21:56.804Z",
  "references/inventory_next/IInventoryService/methods/inventory_next.IInventoryService.createInventoryItems/page.mdx": "2024-12-09T13:21:56.744Z",
@@ -1366,7 +1366,7 @@ export const generatedEditDates = {
  "references/payment/interfaces/payment.JoinerServiceConfig/page.mdx": "2025-01-13T18:05:56.394Z",
  "references/payment/interfaces/payment.JoinerServiceConfigAlias/page.mdx": "2024-12-09T13:22:02.308Z",
  "references/payment/types/payment.JoinerRelationship/page.mdx": "2024-12-09T13:22:02.304Z",
-  "references/payment_provider/classes/payment_provider.AbstractPaymentProvider/page.mdx": "2025-01-27T11:43:56.965Z",
+  "references/payment_provider/classes/payment_provider.AbstractPaymentProvider/page.mdx": "2025-02-07T10:35:24.492Z",
  "references/pricing/IPricingModuleService/methods/pricing.IPricingModuleService.addPriceListPrices/page.mdx": "2024-12-09T13:22:02.928Z",
  "references/pricing/IPricingModuleService/methods/pricing.IPricingModuleService.addPrices/page.mdx": "2024-12-09T13:22:02.868Z",
  "references/pricing/IPricingModuleService/methods/pricing.IPricingModuleService.calculatePrices/page.mdx": "2024-12-09T13:22:02.832Z",
@@ -10,9 +10,18 @@ In this document, you’ll learn how to create an auth provider module and the m

 ---

-## 1. Create Module Directory
+## 1. Create Module Provider Directory

-Start by creating a new directory for your module. For example, `src/modules/my-auth`.
+Start by creating a new directory for your module provider.
+
+If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-auth`.
+If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-auth`.
+
+<Note>
+
+The rest of this guide always uses the `src/modules/my-auth` directory as an example.
+
+</Note>

 ---

@@ -479,6 +488,7 @@ module.exports = defineConfig({
            id: "emailpass",
          },
          {
+            // if module provider is in a plugin, use `plugin-name/providers/my-auth`
            resolve: "./src/modules/my-auth",
            id: "my-auth",
            dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
@@ -10,9 +10,18 @@ In this document, you’ll learn how to create a file provider module and the me

 ---

-## 1. Create Module Directory
+## Create Module Provider Directory

-Start by creating a new directory for your module. For example, `src/modules/my-file`.
+Start by creating a new directory for your module provider.
+
+If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-file`.
+If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-file`.
+
+<Note>
+
+The rest of this guide always uses the `src/modules/my-file` directory as an example.
+
+</Note>

 ---

@@ -251,6 +260,7 @@ module.exports = defineConfig({
            id: "local",
          },
          {
+            // if module provider is in a plugin, use `plugin-name/providers/my-file`
            resolve: "./src/modules/my-file",
            id: "my-file",
            options: {
@@ -10,9 +10,18 @@ In this document, you’ll learn how to create a fulfillment provider module and

 ---

-## 1. Create Module Directory
+## 1. Create Module Provider Directory

-Start by creating a new directory for your module. For example, `src/modules/my-fulfillment`.
+Start by creating a new directory for your module provider.
+
+If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-fulfillment`.
+If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-fulfillment`.
+
+<Note>
+
+The rest of this guide always uses the `src/modules/my-fulfillment` directory as an example.
+
+</Note>

 ---

@@ -534,6 +543,7 @@ module.exports = defineConfig({
            id: "manual",
          },
          {
+            // if module provider is in a plugin, use `plugin-name/providers/my-fulfillment`
            resolve: "./src/modules/my-fulfillment",
            id: "my-fulfillment",
            options: {
@@ -10,9 +10,18 @@ In this document, you’ll learn how to create a notification provider module an

 ---

-## 1. Create Module Directory
+## 1. Create Module Provider Directory

-Start by creating a new directory for your module. For example, `src/modules/my-notification`.
+Start by creating a new directory for your module provider.
+
+If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-notification`.
+If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-notification`.
+
+<Note>
+
+The rest of this guide always uses the `src/modules/my-notification` directory as an example.
+
+</Note>

 ---

@@ -192,6 +201,7 @@ module.exports = defineConfig({
            },
          },
          {
+            // if module provider is in a plugin, use `plugin-name/providers/my-notification`
            resolve: "./src/modules/my-notification",
            id: "my-notification",
            options: {
@@ -10,9 +10,18 @@ In this document, you’ll learn how to create a Payment Provider to be used wit

 ---

-## 1. Create Module Directory
+## 1. Create Module Provider Directory

-Start by creating a new directory for your module. For example, `src/modules/my-payment`.
+Start by creating a new directory for your module provider.
+
+If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-payment`.
+If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-payment`.
+
+<Note>
+
+The rest of this guide always uses the `src/modules/my-payment` directory as an example.
+
+</Note>

 ---

@@ -742,6 +751,7 @@ module.exports = defineConfig({
      options: {
        providers: [
          {
+            // if module provider is in a plugin, use `plugin-name/providers/my-payment`
            resolve: "./src/modules/my-payment",
            id: "my-payment",
            options: {
@@ -22,9 +22,18 @@ const authProviderOptions: FormattingOptionsType = {
      reflection_typeParameters: false,
    },
    startSections: [
-      `## 1. Create Module Directory
+      `## 1. Create Module Provider Directory

-Start by creating a new directory for your module. For example, \`src/modules/my-auth\`.`,
+Start by creating a new directory for your module provider.
+
+If you're creating the module provider in a Medusa application, create it under the \`src/modules\` directory. For example, \`src/modules/my-auth\`.
+If you're creating the module provider in a plugin, create it under the \`src/providers\` directory. For example, \`src/providers/my-auth\`.
+
+<Note>
+
+The rest of this guide always uses the \`src/modules/my-auth\` directory as an example.
+
+</Note>`,
      `## 2. Create the Auth Provider Service

 Create the file \`src/modules/my-auth/service.ts\` that holds the module's main service. It must extend the \`AbstractAuthModuleProvider\` class imported from \`@medusajs/framework/utils\`:
@@ -78,6 +87,7 @@ module.exports = defineConfig({
            id: "emailpass",
          },
          {
+            // if module provider is in a plugin, use \`plugin-name/providers/my-auth\`
            resolve: "./src/modules/my-auth",
            id: "my-auth",
            dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
@@ -22,9 +22,18 @@ const fileOptions: FormattingOptionsType = {
      reflection_typeParameters: false,
    },
    startSections: [
-      `## 1. Create Module Directory
+      `## Create Module Provider Directory

-Start by creating a new directory for your module. For example, \`src/modules/my-file\`.`,
+Start by creating a new directory for your module provider.
+
+If you're creating the module provider in a Medusa application, create it under the \`src/modules\` directory. For example, \`src/modules/my-file\`.
+If you're creating the module provider in a plugin, create it under the \`src/providers\` directory. For example, \`src/providers/my-file\`.
+
+<Note>
+
+The rest of this guide always uses the \`src/modules/my-file\` directory as an example.
+
+</Note>`,
      `## 2. Create the File Provider Service

 Create the file \`src/modules/my-file/service.ts\` that holds the implementation of the module's main service. It must extend the \`AbstractFileProviderService\` class imported from \`@medusajs/framework/utils\`:
@@ -81,6 +90,7 @@ module.exports = defineConfig({
            id: "local",
          },
          {
+            // if module provider is in a plugin, use \`plugin-name/providers/my-file\`
            resolve: "./src/modules/my-file",
            id: "my-file",
            options: {
@@ -22,9 +22,18 @@ const fulfillmentProviderOptions: FormattingOptionsType = {
      reflection_typeParameters: false,
    },
    startSections: [
-      `## 1. Create Module Directory
+      `## 1. Create Module Provider Directory

-Start by creating a new directory for your module. For example, \`src/modules/my-fulfillment\`.`,
+Start by creating a new directory for your module provider.
+
+If you're creating the module provider in a Medusa application, create it under the \`src/modules\` directory. For example, \`src/modules/my-fulfillment\`.
+If you're creating the module provider in a plugin, create it under the \`src/providers\` directory. For example, \`src/providers/my-fulfillment\`.
+
+<Note>
+
+The rest of this guide always uses the \`src/modules/my-fulfillment\` directory as an example.
+
+</Note>`,
      `## 2. Create the Fulfillment Provider Service

 Create the file \`src/modules/my-fulfillment/service.ts\` that holds the module's main service. It must extend the \`AbstractFulfillmentProviderService\` class imported from \`@medusajs/framework/utils\`:
@@ -75,6 +84,7 @@ module.exports = defineConfig({
            id: "manual",
          },
          {
+            // if module provider is in a plugin, use \`plugin-name/providers/my-fulfillment\`
            resolve: "./src/modules/my-fulfillment",
            id: "my-fulfillment",
            options: {
@@ -22,9 +22,18 @@ const notificationOptions: FormattingOptionsType = {
      reflection_typeParameters: false,
    },
    startSections: [
-      `## 1. Create Module Directory
+      `## 1. Create Module Provider Directory

-Start by creating a new directory for your module. For example, \`src/modules/my-notification\`.`,
+Start by creating a new directory for your module provider.
+
+If you're creating the module provider in a Medusa application, create it under the \`src/modules\` directory. For example, \`src/modules/my-notification\`.
+If you're creating the module provider in a plugin, create it under the \`src/providers\` directory. For example, \`src/providers/my-notification\`.
+
+<Note>
+
+The rest of this guide always uses the \`src/modules/my-notification\` directory as an example.
+
+</Note>`,
      `## 2. Create the Notification Provider Service

 Create the file \`src/modules/my-notification/service.ts\` that holds the implementation of the notification service.
@@ -89,6 +98,7 @@ module.exports = defineConfig({
            },
          },
          {
+            // if module provider is in a plugin, use \`plugin-name/providers/my-notification\`
            resolve: "./src/modules/my-notification",
            id: "my-notification",
            options: {
@@ -22,9 +22,18 @@ const paymentProviderOptions: FormattingOptionsType = {
      reflection_typeParameters: false,
    },
    startSections: [
-      `## 1. Create Module Directory
+      `## 1. Create Module Provider Directory

-Start by creating a new directory for your module. For example, \`src/modules/my-payment\`.`,
+Start by creating a new directory for your module provider.
+
+If you're creating the module provider in a Medusa application, create it under the \`src/modules\` directory. For example, \`src/modules/my-payment\`.
+If you're creating the module provider in a plugin, create it under the \`src/providers\` directory. For example, \`src/providers/my-payment\`.
+
+<Note>
+
+The rest of this guide always uses the \`src/modules/my-payment\` directory as an example.
+
+</Note>`,
      `## 2. Create the Payment Provider Service

 Create the file \`src/modules/my-payment/service.ts\` that holds the module's main service. It must extend the \`AbstractPaymentProvider\` class imported from \`@medusajs/framework/utils\`:
@@ -76,6 +85,7 @@ module.exports = defineConfig({
      options: {
        providers: [
          {
+            // if module provider is in a plugin, use \`plugin-name/providers/my-payment\`
            resolve: "./src/modules/my-payment",
            id: "my-payment",
            options: {