Skip to main content

How to Publish a Plugin

In this document, you'll learn how to publish a Medusa plugin to NPM and what are some requirements to keep in mind before publishing.

Prerequisites​

If you haven't created a plugin yet, please check this guide to learn how to create a plugin.

Prepare the Plugin​

package.json Checklist​

Before publishing your plugin, make sure you've set the following fields in your plugin's package.json:

  • nameCopy to Clipboard: The name of your plugin. By convention, all plugin names start with medusaCopy to Clipboard followed by a descriptive name of what the plugin does. For example, medusa-payment-stripeCopy to Clipboard.
  • descriptionCopy to Clipboard: A short description of what the plugin does.
  • authorCopy to Clipboard: Your name or your company's name.
  • repositoryCopy to Clipboard: This includes details about the repository that holds the source code of the plugin. It's an object that holds the following properties:
    • typeCopy to Clipboard: Should be gitCopy to Clipboard.
    • urlCopy to Clipboard: The URL to the repository (for example, the GitHub repository holding the code of your plugin).
  • keywordsCopy to Clipboard: An array of keywords that are related to the plugin. It's required for all Medusa plugins to use the keywords medusa-pluginCopy to Clipboard. Other recommended keywords are:
    • medusa-plugin-analyticsCopy to Clipboard: For plugins that add analytics functionalities or integrations.
    • medusa-plugin-cmsCopy to Clipboard: For plugins that add CMS functionalities or integrations.
    • medusa-plugin-notificationCopy to Clipboard: For plugins that add notification functionalities or integrations.
    • medusa-plugin-paymentCopy to Clipboard: For plugins that add payment functionalities or integrations.
    • medusa-plugin-searchCopy to Clipboard: For plugins that add search functionalities or integrations.
    • medusa-plugin-shippingCopy to Clipboard: For plugins that add shipping functionalities or integrations.
    • medusa-plugin-storageCopy to Clipboard: For plugins that add a file service or storage integration.
    • medusa-plugin-sourceCopy to Clipboard: For plugins that help migrate or import data into Medusa from another platform.
    • medusa-plugin-storefrontCopy to Clipboard: For storefronts that can be integrated with a Medusa server.
    • medusa-plugin-otherCopy to Clipboard: For any other type of plugin.

Scripts in package.json​

Make sure you add the publishCopy to Clipboard command to your scriptsCopy to Clipboard field and make the following change to the buildCopy to Clipboard command:

package.json
"build": "babel src --out-dir . --ignore **/__tests__ --extensions \".ts,.js\"",
"prepare": "cross-env NODE_ENV=production npm run build"
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

The buildCopy to Clipboard command ensures that the plugin's built files are placed as explained in the plugin structure section of the Create Plugin documentation.

The prepareCopy to Clipboard command facilitates your publishing process. You would typically run this script before publishing your plugin.

This new script requires installing the package cross-envCopy to Clipboard as a development dependency:

yarn add --dev cross-env
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

Plugin Structure​

Make sure your plugin's structure is as described in the Create Plugin documentation. If you've made the changes mentioned in the above section to the scripts in package.jsonCopy to Clipboard, you should have the correct structure when you run the prepareCopy to Clipboard command.

NPM Ignore File​

Not all files that you use while developing your plugin are necessary to be published.

For example, the files you add in the srcCopy to Clipboard directory are compiled to the root of the plugin directory before publishing. Then, when a developer installs your plugin, they’ll just be using the files in the root.

So, you can ignore files and directories like srcCopy to Clipboard from the final published NPM package.

To do that, create the file .npmignoreCopy to Clipboard with the following content:

.npmignore
/lib
node_modules
.DS_store
.env*
/*.js
!index.js
yarn.lock
src
.gitignore
.eslintrc
.babelrc
.prettierrc

# These are files that are included in a
# Medusa project and can be removed from a
# plugin project
medusa-config.js
Dockerfile
medusa-db.sql
develop.sh
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

Publish Plugin​

This section explains how to publish your plugin to NPM.

Before you publish a plugin, you must create an account on NPM.

Run Prepare Command​

Before you publish or update your plugin, make sure to run the prepareCopy to Clipboard command defined earlier:

yarn run prepare
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

Login​

In your terminal, log in with your NPM account:

npm login
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

You’ll be asked to enter your NPM email and password.

Publish Plugin Package​

Once you’re logged in, you can publish your package with the following command:

npm publish
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

Your package is then published on NPM and everyone can use it and install it.

Install Plugin​

To install your published plugin, you can run the following command on any Medusa server project:

yarn add medusa-plugin-custom
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

Update Plugin​

To update your plugin at a later point, you can run the following command to change the NPM version:

npm version <type>
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

Where <type>Copy to Clipboard indicates the type of version update you’re publishing. For example, it can be majorCopy to Clipboard or minorCopy to Clipboard. You can see the full list of types in NPM’s documentation.

Then, publish the new update:

npm publish
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

See Also​