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.
Prerequisites
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
In your package.json
file, add or update the following fields:
{
// other fields
"main": "dist/index.js",
"publishConfig": {
"access": "public"
},
"files": [
"dist"
],
"devDependencies": {
"@medusajs/types": "^0.0.2",
"cross-env": "^5.2.1",
"typescript": "^4.4.4"
},
"scripts": {
"watch": "tsc --build --watch",
"prepare": "cross-env NODE_ENV=production npm run build",
"build": "tsc --build",
},
"dependencies": {
"@medusajs/modules-sdk": "^0.1.0",
}
}
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 NPMwatch
: (optional, for development) can be used to re-build your module whenever any changes occur without having to manually trigger thebuild
.
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:
{
"compilerOptions": {
"lib": [
"es2020"
],
"target": "2020",
"outDir": "./dist",
"esModuleInterop": true,
"declaration": true,
"module": "commonjs",
"moduleResolution": "node",
"emitDecoratorMetadata": true,
"experimentalDecorators": true,
"sourceMap": true,
"noImplicitReturns": true,
"strictNullChecks": true,
"strictFunctionTypes": true,
"noImplicitThis": true,
"allowJs": true,
"skipLibCheck": true,
},
"include": ["src"],
"exclude": [
"dist",
"./src/**/__tests__",
"./src/**/__mocks__",
"./src/**/__fixtures__",
"node_modules"
]
}
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:
Login
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.
Install Module
To install your published module, you can run the following command on any Medusa backend project:
Where module-name
is the name of your module.
Add Module to medusa-config.js
In medusa-config.js
on your Medusa backend, add your module to the exported configurations:
Where <module-name>
is the name of your NPM package.
You can learn more about the available options in the Create Module documentation.
Update Module
To update your module at a later point, you can run the following command to change the NPM version:
Where <type>
indicates the type of version update you’re publishing. For example, it can be major
or minor
. You can see the full list of types in NPM’s documentation.
Then, publish the new update: