How to Publish a Module
In this document, you'll learn how to prepare and publish your custom module to NPM, then how to install it in the Medusa backend.
This guide assumes you've already created a custom module. If not, follow this guide first to create a module.
You also need an NPM account to publish the module with.
Step 1: Create an NPM Project
If your module isn't located in an NPM project already, you must create one first that will hold your module.
To do that, run the following commands to create a directory and initialize an NPM project in it:
You’ll be asked a couple of questions related to your package, such as its name or license. You can keep the default for now or set them right away.
Once you’re done, you should have a
package.json created in the directory.
Step 2: Changes to package.json
package.json file, add or update the following fields:
// other fields
"watch": "tsc --build --watch",
"prepare": "cross-env NODE_ENV=production npm run build",
"build": "tsc --build",
This adds the necessary dependencies for development and publishing, including the
@medusajs/modules-sdk package. It also adds the following scripts:
build: can be used to manually build your module.
prepare: can be used to prepare your module for publishing on NPM
watch: (optional, for development) can be used to re-build your module whenever any changes occur without having to manually trigger the
Step 3: Configure tsconfig.json
If you don't already have a
tsconfig.json file, create one in the root of your NPM project with the following content:
This allows you to use the recommended TypeScript configurations and sets the output directory to
dist. This is essential for preparing your module for publishing.
Step 4: Change Module Structure
To ensure that the files are built from the
src directory to the
dist directory, make sure to move the module content to a
src directory inside the new NPM project.
Step 5: Publish and Use Module
This section explains how to publish your module to NPM.
Run Prepare Command
Before you publish or update your module, make sure to run the
prepare command defined earlier:
In your terminal, log in with your NPM account:
You’ll be asked to enter your NPM email and password.
Publish Module Package
Once you’re logged in, you can publish your package with the following command:
Your package is then published on NPM and everyone can use it and install it.
To install your published module, you can run the following command on any Medusa backend project:
module-name is the name of your module.
Add Module to medusa-config.js
medusa-config.js on your Medusa backend, add your module to the exported configurations:
<module-name> is the name of your NPM package.
You can learn more about the available options in the Create Module documentation.
To update your module at a later point, you can run the following command to change the NPM version:
<type> indicates the type of version update you’re publishing. For example, it can be
minor. You can see the full list of types in NPM’s documentation.
Then, publish the new update: