Create a Plugin

In this chapter, you'll learn how to create a Medusa plugin and publish it.

A plugin is a package of reusable Medusa customizations that you can install in any Medusa application. By creating and publishing a plugin, you can reuse your Medusa customizations across multiple projects or share them with the community.

1. Create a Plugin Project#

Plugins are created in a separate Medusa project. This makes the development and publishing of the plugin easier. Later, you'll install that plugin in your Medusa application to test it out and use it.

Medusa's create-medusa-app CLI tool provides the option to create a plugin project. Run the following command to create a new plugin project:

Terminal
❯npx create-medusa-app my-plugin --plugin

This will create a new Medusa plugin project in the my-plugin directory.

Plugin Directory Structure#

After the installation is done, the plugin structure will look like this:

• src/: Contains the Medusa customizations.
• src/admin: Contains admin extensions.
• src/api: Contains API routes and middlewares. You can add store, admin, or any custom API routes.
• src/jobs: Contains scheduled jobs.
• src/links: Contains module links.
• src/modules: Contains modules.
• src/provider: Contains module providers.
• src/subscribers: Contains subscribers.
• src/workflows: Contains workflows. You can also add hooks under src/workflows/hooks.
• package.json: Contains the plugin's package information, including general information and dependencies.
• tsconfig.json: Contains the TypeScript configuration for the plugin.

2. Prepare Plugin#

Package Name#

Before developing, testing, and publishing your plugin, make sure its name in package.json is correct. This is the name you'll use to install the plugin in your Medusa application.

For example:

package.json
1{2  "name": "@myorg/plugin-name",3  // ...4}

Package Keywords#

In addition, make sure that the keywords field in package.json includes the keyword medusa-plugin and medusa-v2. This helps Medusa list community plugins on the Medusa website:

package.json
1{2  "keywords": [3    "medusa-plugin",4    "medusa-v2"5  ],6  // ...7}

Package Dependencies#

In the package.json file you must have the Medusa dependencies as devDependencies and peerDependencies. In addition, you must have @swc/core as a devDependency, as it's used by the plugin CLI tools.

For example, assuming 2.5.0 is the latest Medusa version:

package.json
1{2  "devDependencies": {3    "@medusajs/admin-sdk": "2.5.0",4    "@medusajs/cli": "2.5.0",5    "@medusajs/framework": "2.5.0",6    "@medusajs/medusa": "2.5.0",7    "@medusajs/test-utils": "2.5.0",8    "@medusajs/ui": "4.0.4",9    "@medusajs/icons": "2.5.0",10    "@swc/core": "1.5.7",11  },12  "peerDependencies": {13    "@medusajs/admin-sdk": "2.5.0",14    "@medusajs/cli": "2.5.0",15    "@medusajs/framework": "2.5.0",16    "@medusajs/test-utils": "2.5.0",17    "@medusajs/medusa": "2.5.0",18    "@medusajs/ui": "4.0.3",19    "@medusajs/icons": "2.5.0",20  }21}

3. Publish Plugin Locally for Development and Testing#

Medusa's CLI tool provides commands to simplify developing and testing your plugin in a local Medusa application. You start by publishing your plugin in the local package registry, then install it in your Medusa application. You can then watch for changes in the plugin as you develop it.

Publish and Install Local Package#

The first time you create your plugin, you need to publish the package into a local package registry, then install it in your Medusa application. This is a one-time only process.

To publish the plugin to the local registry, run the following command in your plugin project:

Plugin project
❯npx medusa plugin:publish

This command uses Yalc under the hood to publish the plugin to a local package registry. The plugin is published locally under the name you specified in package.json.

Next, navigate to your Medusa application:

Medusa application
❯cd ~/path/to/medusa-app

Make sure to replace ~/path/to/medusa-app with the path to your Medusa application.

Then, if your project was created before v2.3.1 of Medusa, make sure to install yalc as a development dependency:

npm
yarn
pnpm
❯npm install --save-dev yalc

After that, run the following Medusa CLI command to install the plugin:

Medusa application
❯npx medusa plugin:add @myorg/plugin-name

Make sure to replace @myorg/plugin-name with the name of your plugin as specified in package.json. Your plugin will be installed from the local package registry into your Medusa application.

Register Plugin in Medusa Application#

After installing the plugin, you need to register it in your Medusa application in the configurations defined in medusa-config.ts.

Add the plugin to the plugins array in the medusa-config.ts file:

medusa-config.ts
1module.exports = defineConfig({2  // ...3  plugins: [4    {5      resolve: "@myorg/plugin-name",6      options: {},7    },8  ],9})

The plugins configuration is an array of objects where each object has a resolve key whose value is the name of the plugin package.

Pass Module Options through Plugin

Each plugin configuration also accepts an options property, whose value is an object of options to pass to the plugin's modules.

For example:

medusa-config.ts
1module.exports = defineConfig({2  // ...3  plugins: [4    {5      resolve: "@myorg/plugin-name",6      options: {7        apiKey: true,8      },9    },10  ],11})

The options property in the plugin configuration is passed to all modules in the plugin. Learn more about module options in this chapter.

Watch Plugin Changes During Development#

While developing your plugin, you can watch for changes in the plugin and automatically update the plugin in the Medusa application using it. This is the only command you'll continuously need during your plugin development.

To do that, run the following command in your plugin project:

Plugin project
❯npx medusa plugin:develop

This command will:

• Watch for changes in the plugin. Whenever a file is changed, the plugin is automatically built.
• Publish the plugin changes to the local package registry. This will automatically update the plugin in the Medusa application using it. You can also benefit from real-time HMR updates of admin extensions.

Start Medusa Application#

You can start your Medusa application's development server to test out your plugin:

npm
yarn
pnpm
❯npm run dev

While your Medusa application is running and the plugin is being watched, you can test your plugin while developing it in the Medusa application.

4. Create Customizations in the Plugin#

You can now build your plugin's customizations. The following guide explains how to build different customizations in your plugin.

While building those customizations, you can test them in your Medusa application by watching the plugin changes and starting the Medusa application.

Generating Migrations for Modules#

During your development, you may need to generate migrations for modules in your plugin. To do that, use the plugin:db:generate command:

Plugin project
❯npx medusa plugin:db:generate

This command generates migrations for all modules in the plugin. You can then run these migrations on the Medusa application that the plugin is installed in using the db:migrate command:

Medusa application
❯npx medusa db:migrate

Importing Module Resources#

Your plugin project should have the following exports in package.json:

package.json
1{2  "exports": {3    "./package.json": "./package.json",4    "./workflows": "./.medusa/server/src/workflows/index.js",5    "./.medusa/server/src/modules/*": "./.medusa/server/src/modules/*/index.js",6    "./providers/*": "./.medusa/server/src/providers/*/index.js",7    "./*": "./.medusa/server/src/*.js"8  }9}

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.
• ./.medusa/server/src/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:

Code
1import { Workflow1, Workflow2 } from "@myorg/plugin-name/workflows"2import BlogModule from "@myorg/plugin-name/modules/blog"3// import other files created in plugin like ./src/types/blog.ts4import BlogType from "@myorg/plugin-name/types/blog"

And you can register a module provider in the Medusa application's medusa-config.ts like this:

medusa-config.ts
1module.exports = defineConfig({2  // ...3  modules: [4    {5      resolve: "@medusajs/medusa/notification",6      options: {7        providers: [8          {9            resolve: "@myorg/plugin-name/providers/my-notification",10            id: "my-notification",11            options: {12              channels: ["email"],13              // provider options...14            },15          },16        ],17      },18    },19  ],20})

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:

5. Publish Plugin to NPM#

Medusa's CLI tool provides a command that bundles your plugin to be published to npm. Once you're ready to publish your plugin publicly, run the following command in your plugin project:

Terminal
❯npx medusa plugin:build

The command will compile an output in the .medusa/server directory.

You can now publish the plugin to npm using the NPM CLI tool. Run the following command to publish the plugin to npm:

Terminal
❯npm publish

If you haven't logged in before with your NPM account, you'll be asked to log in first. Then, your package is published publicly to be used in any Medusa application.

Install Public Plugin in Medusa Application#

You install a plugin that's published publicly using your package manager. For example:

npm
yarn
pnpm
❯npm install @myorg/plugin-name

Where @myorg/plugin-name is the name of your plugin as published on NPM.

Then, register the plugin in your Medusa application's configurations as explained in this section.

Update a Published Plugin#

If you've published a plugin and you've made changes to it, you'll have to publish the update to NPM again.

First, run the following command to change the version of the plugin:

Terminal
❯npm version <type>

Where <type> indicates the type of version update you’re publishing. For example, it can be major or minor. Refer to the npm version documentation for more information.

Then, re-run the same commands for publishing a plugin:

Terminal
❯npx medusa plugin:build❯npm publish

This will publish an updated version of your plugin under a new version.