on GitHub" data-tooltip-id=":Rblcldtb:">v2.6·
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.
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:
This will create a new Medusa plugin project in the my-plugin
directory.
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.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:
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:
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:
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}
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.
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:
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:
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:
After that, run the following Medusa CLI command to install the plugin:
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.
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:
The plugins
configuration is an array of objects where each object has a resolve
key whose value is the name of the plugin package.
Each plugin configuration also accepts an options
property, whose value is an object of options to pass to the plugin's modules.
For example:
The options
property in the plugin configuration is passed to all modules in the plugin. Learn more about module options in this chapter.
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:
This command will:
You can start your Medusa application's development server to test out your plugin:
While your Medusa application is running and the plugin is being watched, you can test your plugin while developing it in the Medusa application.
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.
During your development, you may need to generate migrations for modules in your plugin. To do that, use the plugin:db:generate
command:
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:
Your plugin project should have the following exports in 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}
./package.json
and ./providers
, these exports are only a recommendation. You can cherry-pick the files and directories you want to export.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:
@myorg/plugin-name
is the plugin package's name.And you can register a module provider in the Medusa application's medusa-config.ts
like this:
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.
To learn how to create module providers, refer to the following guides:
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:
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:
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.
You install a plugin that's published publicly using your package manager. For example:
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.
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:
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:
This will publish an updated version of your plugin under a new version.