medusajs · kodiakhq · Jan 27, 2025 · Jan 16, 2025 · Jan 16, 2025 · Jan 16, 2025
@@ -0,0 +1,17 @@
+export const metadata = {
+  title: `${pageNumber} Re-Use Customizations with Plugins`,
+}
+
+# {metadata.title}
+
+In the previous chapters, you've learned important concepts related to creating modules, implementing commerce features in workflows, exposing those features in API routes, customizing the Medusa Admin dashboard with Admin Extensions, and integrating third-party systems.
+
+You've implemented the brands example within a single Medusa application. However, this approach is not scalable when you want to reuse your customizations across multiple projects.
+
+To reuse your customizations across multiple Medusa applications, such as implementing brands in different projects, you can create a plugin. A plugin is an NPM package that encapsulates your customizations and can be installed in any Medusa application. Plugins can include modules, workflows, API routes, Admin Extensions, and more.
+
+![Diagram showcasing how the Brand Plugin would add its resources to any application it's installed in](https://res.cloudinary.com/dza7lstvk/image/upload/v1737540091/Medusa%20Book/brand-plugin_bk9zi9.jpg)
+
+Medusa provides the tooling to create a plugin package, test it in a local Medusa application, and publish it to NPM.
+
+To learn more about plugins and how to create them, refer to [this chapter](../../fundamentals/plugins/page.mdx).
@@ -198,7 +198,7 @@ For example, assuming you have the [Order, Product, and OrderProduct models from
 class HelloModuleService extends MedusaService({
   Order,
   Product,
-  OrderProduct
+  OrderProduct,
 }) {}
 ```
 
@@ -212,16 +212,16 @@ const orderProduct = await helloModuleService.createOrderProducts({
   order_id: "123",
   product_id: "123",
   metadata: {
-    test: true
-  }
+    test: true,
+  },
 })
 
 // update order-product association
 const orderProduct = await helloModuleService.updateOrderProducts({
   id: "123",
   metadata: {
-    test: false
-  }
+    test: false,
+  },
 })
 
 // delete order-product association

@@ -217,29 +217,29 @@ export const manyToManyColumnHighlights = [
 ]
 
 ```ts highlights={manyToManyColumnHighlights}
-import { model } from "@medusajs/framework/utils";
+import { model } from "@medusajs/framework/utils"
 
 export const Order = model.define("order_test", {
   id: model.id().primaryKey(),
   products: model.manyToMany(() => Product, {
-    pivotEntity: () => OrderProduct
-  })
+    pivotEntity: () => OrderProduct,
+  }),
 })
 
 export const Product = model.define("product_test", {
   id: model.id().primaryKey(),
-  orders: model.manyToMany(() => Order)
+  orders: model.manyToMany(() => Order),
 })
 
 export const OrderProduct = model.define("orders_products", {
   id: model.id().primaryKey(),
   order: model.belongsTo(() => Order, {
-    mappedBy: "products"
+    mappedBy: "products",
   }),
   product: model.belongsTo(() => Product, {
-    mappedBy: "orders"
+    mappedBy: "orders",
   }),
-  metadata: model.json().nullable()
+  metadata: model.json().nullable(),
 })
 ```
 

@@ -8,9 +8,7 @@ In this chapter, you’ll learn about passing options to your module from the Me
 
 ## What are Module Options?
 
-A module can receive options to customize or configure its functionality.
-
-For example, if you’re creating a module that integrates a third-party service, you’ll want to receive the integration credentials in the options rather than adding them directly in your code.
+A module can receive options to customize or configure its functionality. For example, if you’re creating a module that integrates a third-party service, you’ll want to receive the integration credentials in the options rather than adding them directly in your code.
 
 ---
 
@@ -20,7 +18,7 @@ To pass options to a module, add an `options` property to the module’s configu
 
 For example:
 
-```js title="medusa-config.ts"
+```ts title="medusa-config.ts"
 module.exports = defineConfig({
   // ...
   modules: [
@@ -36,6 +34,28 @@ module.exports = defineConfig({
 
 The `options` property’s value is an object. You can pass any properties you want.
 
+### Pass Options to a Module in a Plugin
+
+If your module is part of a plugin, you can pass options to the module in the plugin’s configuration.
+
+For example:
+
+```ts title="medusa-config.ts"
+import { defineConfig } from "@medusajs/framework/utils"
+module.exports = defineConfig({
+  plugins: [
+    {
+      resolve: "@myorg/plugin-name",
+      options: {
+        capitalize: true,
+      },
+    },
+  ],
+})
+```
+
+The `options` property in the plugin configuration is passed to all modules in a plugin.
+
 ---
 
 ## Access Module Options in Main Service

@@ -16,6 +16,18 @@ Medusa removes this overhead by allowing you to easily write custom modules that
 
 As you learn more about Medusa, you will see that modules are central to customizations and integrations. With modules, your Medusa application can turn into a middleware solution for your commerce ecosystem.
 
+<Note title="Use a module if" type="success">
+
+- You want to build a custom feature related to a single domain or integrate a third-party service.
+
+</Note>
+
+<Note title="Don't use a module if" type="error">
+
+- You want to create a reusable package of customizations that include not only modules, but also API routes, workflows, and other customizations. Instead, use a [plugin](../plugins/page.mdx).
+
+</Note>
+
 ---
 
 ## How to Create a Module?
@@ -136,6 +148,12 @@ You export `BLOG_MODULE` to reference the module's name more reliably when resol
 
 ### 4. Add Module to Medusa's Configurations
 
+<Note>
+
+If you're creating the module in a plugin, this step isn't required as the module is registered when the plugin is registered. Learn more about plugins in [this documentation](../plugins/page.mdx).
+
+</Note>
+
 Once you finish building the module, add it to Medusa's configurations to start using it. Medusa will then register the module's main service in the Medusa container, allowing you to resolve and use it in other customizations.
 
 In `medusa-config.ts`, add a `modules` property and pass an array with your custom module:
@@ -165,6 +183,12 @@ You don't have to write migrations yourself. Medusa's CLI tool has a command tha
 
 To generate a migration for the Blog Module, run the following command in your Medusa application's directory:
 
+<Note>
+
+If you're creating the module in a plugin, use the [plugin\:db\:generate command](!resources!/medusa-cli/commands/plugin#plugindbgenerate) instead.
+
+</Note>
+
 ```bash
 npx medusa db:generate blog
 ```
@@ -193,6 +217,12 @@ In the migration class, the `up` method creates the table `post` and defines its
 
 To reflect the changes in the generated migration file on the database, run the `db:migrate` command:
 
+<Note>
+
+If you're creating the module in a plugin, run this command on the Medusa application that the plugin is installed in.
+
+</Note>
+
 ```bash
 npx medusa db:migrate
 ```