How to Create a Plugin
In this document, you’ll learn how to create a plugin and some tips for development. If you’re interested to learn more about what plugins are and where to find available official and community plugins, check out the overview document.
Alternatively, you can follow this recipe to create a plugin with step-by-step guidance.
Prerequisites
You must have an existing Medusa project that you want to create the plugin with.
The recommended way to create a plugin is using the new
command from Medusa CLI:
Where medusa-plugin-custom
is the name of the plugin you’re creating. In Medusa, plugins are named based on their functionalities.
By convention, all plugin names start with medusa
followed by a descriptive name of what the plugin does. For example, the Stripe plugin is named medusa-payment-stripe
.
Changes to package.json
Package Name
By default, your package name in package.json
will be medusa-starter-default
. This should instead be the name of your plugin. For example, the Stripe plugin's package name is medusa-payment-stripe
.
Change Dependencies
A basic Medusa backend installed with the medusa new
command has dependencies that are necessary for the backend, but not necessary for plugins.
For example, can remove the dependencies medusa-fulfillment-manual
, medusa-payment-manual
, and medusa-payment-stripe
as they are fulfillment and payment plugins necessary for a Medusa backend, but not for a plugin. The same goes for modules like @medusajs/cache-inmemory
.
Additionally, you can remove @medusajs/medusa-cli
as you don’t need to use the Medusa CLI while developing a plugin.
You should also add @medusajs/medusa
as a peer dependency:
Where YOUR_MEDUSA_VERSION
is the version you're using of the Medusa core package. You should be able to find it under devDependencies
.
Once you’re done making these changes, re-run the install command to update your node_modules
directory:
Then, make sure to remove the plugins and modules you removed from medusa-config.js
:
Changes for Admin Plugins
If your plugin contains customizations to the admin dashboard, it's recommended to create different tsconfig
files for backend and admin customizations, then modify the scripts in package.json
to handle building backend and admin customizations separately.
These changes may already be available in your Medusa project. They're included here for reference purposes.
Start by updating your tsconfig.json
with the following configurations:
{
"compilerOptions": {
"target": "es2019",
"module": "commonjs",
"allowJs": true,
"checkJs": false,
"jsx": "react-jsx",
"declaration": true,
"outDir": "./dist",
"rootDir": "./src",
"experimentalDecorators": true,
"emitDecoratorMetadata": true,
"noEmit": false,
"strict": false,
"moduleResolution": "node",
"esModuleInterop": true,
"resolveJsonModule": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/"],
"exclude": [
"dist",
"build",
".cache",
"tests",
"**/*.spec.js",
"**/*.spec.ts",
"node_modules",
".eslintrc.js"
]
}
The important changes to note here are the inclusion of the field "jsx": "react-jsx"
and the addition of "build"
and “.cache”
to exclude
.
The addition of "jsx": "react-jsx"
specified how should TypeScript transform JSX, and excluding build
and .cache
ensures that TypeScript ignores build and development files.
Next, create the file tsconfig.server.json
with the following content:
This is the configuration that will be used to transpile your custom backend code, such as services or entities. The important part is that it excludes src/admin
as that is where your Admin code will live.
Then, create the file tsconfig.admin.json
with the following content:
This is the configuration that will be used when transpiling your admin code.
Finally, update the build
scripts in your project and add a new prepare
command:
"scripts": {
// other scripts...
"build": "cross-env npm run clean && npm run build:server && npm run build:admin",
"build:server": "cross-env npm run clean && tsc -p tsconfig.json",
"build:admin": "cross-env medusa-admin build",
"prepare": "cross-env NODE_ENV=production npm run build:server && medusa-admin bundle"
}
Each of these scripts do the following:
build
: used to build resources for both admin and backend for development. You'll typically use this script during your plugin development.build:server
: used to build backend resources for development.build:admin
: used to build admin resources for development.prepare
: used to build resources for publishing. You'll typically use this script during plugin testing and publishing.
Furthermore, make sure to add react
to peerDependencies
along with react-router-dom
if you're using it:
Delete Irrelevant Files
If you've installed the Medusa backend using the create-medusa-app command, you might find files under the src
sub-directories that aren't necessary for your plugin development. For example, src/model/onboarding.ts
or migrations under the src/migrations
directory.
Make sure to delete these files if you're not using them in your plugin.
Plugin Development
Plugin Structure
While developing your plugin, you can create your TypeScript or JavaScript files under the src
directory. This includes creating services, API Routes, migrations, and other resources.
However, before you test the changes on a Medusa backend or publish your plugin, you must transpile your files and move them either to a dist
directory or to the root of the plugin's directory.
For example, if you have an API Route in src/api/store/custom/route.ts
, after running the build
or watch
commands as defined earlier, the file should be transpiled into dist/api/store/custom/route.ts
in your plugin's root. You can alternative transpile them into the api/store/custom/route.ts
in your plugin's root.
Development Resources
This guide doesn't cover how to create different files and components. If you’re interested in learning how to do that, you can check out these guides:
Learn how to create an entity.
Learn how to create a service.
Learn how to create an API Route.
Learn how to create a subscriber.
Learn how to create an admin widget.
Learn how to create an admin UI route.
If you're developing something specific, such as a payment processor plugin, you can follow one of the following guides to learn how to create different services within your plugin.
Learn how to create a payment processor.
Learn how to create a fulfillment provider.
Learn how to create a search service.
Learn how to create a file service.
Learn how to create a notification service.
Plugin Options
Plugins often allow developers that will later use them to provide their own option. For example, you can allow developers to specify the API key of a service you’re integrating.
Developers that use your plugin will pass options to your plugin in the plugins
array in medusa-config.js
:
In your plugin's services, you can have access to the option in their constructor. The options are passed as a second parameter to the constructor
method.
For example:
Make sure to include in the README of your plugin the options that can be passed to a plugin.
enableUI Plugin Option
All plugins accept an option named enableUI
. This option is useful mainly if your plugin contains admin customizations. It allows users to enable or disable admin customizations in the admin dashboard.
A developer using your plugin can pass the enableUI
option as part of the plugin's options:
If you're passing your plugin options to third-party services, make sure to omit it from the plugin options you receive in your resources, such as services. The enableUI
option will always be passed as part of your plugin options.
For example:
// In a service in your plugin
class MyService extends TransactionBaseService {
constructor(container, options) {
super(container)
// options contains plugin options
const { enableUI, ...otherOptions } = options
// pass otherOptions to a third-party service
const client = new Client(otherOptions)
}
// ...
}
enableUI
's default value is false
if not provided by the plugin users. This means that it must be enabled manually in a plugin's option for the customizations to appear in the admin dashboard.
Test Your Plugin
While you develop your plugin, you’ll need to test it on an actual Medusa backend. This can be done using the npm link command.
Step 1: Build Changes
- Without Admin Customizations
- With Admin Customizations
In the root of your plugin directory, run the prepare
command:
If the prepare
script is not available in your project, you can find it in this section.
Step 2: Link Package
In the root of your plugin directory, run the following command:
Then, in the directory of the Medusa backend you want to test the plugin on, run the following command:
Where medusa-plugin-custom
is the package name of your plugin.
Step 3: Remove Medusa Dependency
As your plugin has the @medusajs/medusa
package installed, and the Medusa backend has @medusajs/medusa
installed as well, this can cause dependency errors.
To avoid that, remove the @medusajs
directory from the node_modules
of your plugin's directory. For Unix-based operating systems you can use the following command:
Step 4: Add Plugin to Configurations
In the medusa-config.js
file of the Medusa backend you're testing the plugin on, add your custom plugin to the plugins
array:
Make sure to change medusa-plugin-custom
with the name of your plugin. Also, if your plugin has admin customizations, make sure to include the enableUI option.
(Optional) Step 5: Run Migrations
If your plugin includes migrations, run the following command in the Medusa backend's directory:
Step 6: Run the Medusa Backend
In the directory of the Medusa backend, start the backend with the dev
command passing it the --preserve-symlinks
option:
Making Changes to the Plugin
While testing your plugin, if you need to make changes you need to re-install the plugin's dependencies:
Then, after making the changes, run the steps one, three, and six mentioned above.
Troubleshoot Errors
Error: The class must be a valid service implementation
Please make sure that your plugin is following the correct structure. If the error persists then please try the following fix:
cd <BACKEND_PATH>/node_modules/medusa-interfaces
yarn link
cd <BACKEND_PATH>/node_modules/@medusajs/medusa
yarn link
cd <PLUGIN_PATH>
rm -rf node_modules/medusa-interfaces
rm -rf node_modules/@medusajs/medusa
yarn link medusa-interfaces
yarn link @medusajs/medusa
yarn link
cd <BACKEND_PATH>
yarn link your-plugin
cd <BACKEND_PATH>/node_modules/medusa-interfaces
pnpm link
cd <BACKEND_PATH>/node_modules/@medusajs/medusa
pnpm link
cd <PLUGIN_PATH>
rm -rf node_modules/medusa-interfaces
rm -rf node_modules/@medusajs/medusa
pnpm link medusa-interfaces
pnpm link @medusajs/medusa
pnpm link
cd <BACKEND_PATH>
pnpm link your-plugin
Where <BACKEND_PATH>
is the path to your Medusa backend and <PLUGIN_PATH>
is the path to your plugin.
This links the medusa-interfaces
and @medusajs/medusa
packages from your medusa-backend
to your plugin directory and then links your plugin to your medusa-backend
.
APIs not loading
If the APIs you added to your Medussa backend are not loading then please try the following steps:
Where <BACKEND_PATH>
is the path to your Medusa backend, <PLUGIN_PATH>
is the path to your plugin and <PLUGIN_NAME>
is the name of your plugin as it is in your plugin package.json
file.
Publish Plugin
Once you're done with the development of the plugin, you can publish it to NPM so that other Medusa developers and users can use it.
Please refer to this guide on required steps to publish a plugin.