179 lines
6.5 KiB
Plaintext
179 lines
6.5 KiB
Plaintext
---
|
||
description: 'Learn how to publish a Medusa plugin to NPM. This guide lists some check lists to ensure you have implemented before publishing, as well as required steps.'
|
||
addHowToData: true
|
||
---
|
||
|
||
import Tabs from '@theme/Tabs';
|
||
import TabItem from '@theme/TabItem';
|
||
|
||
# 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. Afterwards, your plugin will be published on the [Medusa Plugins page](https://medusajs.com/plugins/).
|
||
|
||
## Prerequisites
|
||
|
||
If you haven't created a plugin yet, please check [this guide to learn how to create a plugin](./create.mdx).
|
||
|
||
---
|
||
|
||
## Prepare Plugin
|
||
|
||
### package.json Checklist
|
||
|
||
Before publishing your plugin, make sure you've set the following fields in your plugin's package.json:
|
||
|
||
- `name`: The name of your plugin. By convention, all plugin names start with `medusa` followed by a descriptive name of what the plugin does. For example, `medusa-payment-stripe`.
|
||
- `description`: A short description of what the plugin does.
|
||
- `author`: Your name or your company's name.
|
||
- `repository`: This includes details about the repository that holds the source code of the plugin. It's an object that holds the following properties:
|
||
- `type`: Should be `git`.
|
||
- `url`: The URL to the repository (for example, the GitHub repository holding the code of your plugin).
|
||
- `keywords`: An array of keywords that are related to the plugin. It's required for all Medusa plugins to use the keywords `medusa-plugin`. Other recommended keywords are:
|
||
- `medusa-plugin-analytics`: For plugins that add analytics functionalities or integrations.
|
||
- `medusa-plugin-cms`: For plugins that add CMS functionalities or integrations.
|
||
- `medusa-plugin-notification`: For plugins that add notification functionalities or integrations.
|
||
- `medusa-plugin-payment`: For plugins that add payment functionalities or integrations.
|
||
- `medusa-plugin-search`: For plugins that add search functionalities or integrations.
|
||
- `medusa-plugin-shipping`: For plugins that add shipping functionalities or integrations.
|
||
- `medusa-plugin-storage`: For plugins that add a file service or storage integration.
|
||
- `medusa-plugin-source`: For plugins that help migrate or import data into Medusa from another platform.
|
||
- `medusa-plugin-storefront`: For storefronts that can be integrated with a Medusa backend.
|
||
- `medusa-plugin-admin`: For plugins that include only admin customizations.
|
||
- `medusa-plugin-other`: For any other type of plugin.
|
||
|
||
### Scripts in package.json
|
||
|
||
<Tabs groupId="plugin-preference">
|
||
<TabItem value="without-admin" label="Without Admin Customizations" default>
|
||
Make sure you add the `publish` script to your `scripts` field:
|
||
|
||
```json title="package.json"
|
||
"scripts": {
|
||
// other scripts...
|
||
"build": "cross-env npm run clean && tsc -p tsconfig.json",
|
||
"prepare": "cross-env NODE_ENV=production npm run build"
|
||
}
|
||
```
|
||
|
||
The `build` script ensures that the plugin's built files are placed as explained in the [plugin structure](./create.mdx#plugin-structure) section of the Create Plugin documentation.
|
||
|
||
The `prepare` script facilitates your publishing process. You would typically run this script before publishing your plugin.
|
||
</TabItem>
|
||
<TabItem value="with-admin" label="With Admin Customizations">
|
||
First, make sure to change `tsconfig` files as recommended in the [create guide](./create.mdx#changes-for-admin-plugins).
|
||
|
||
Then, add the following `prepare` and `build` scripts to your `scripts`
|
||
|
||
```json title="package.json"
|
||
"scripts": {
|
||
// other scripts...
|
||
"build:server": "cross-env npm run clean && tsc -p tsconfig.json",
|
||
"prepare": "cross-env NODE_ENV=production npm run build:server && medusa-admin bundle"
|
||
}
|
||
```
|
||
|
||
The `build:server` script builds the resources of the backend for development and ensures they are placed as explained in the [plugin structure](./create.mdx#plugin-structure) section of the Create Plugin documentation.
|
||
|
||
The `prepare` script creates a production build of both backend and admin resources.
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### Plugin Structure
|
||
|
||
Make sure your plugin's structure is as described in the [Create Plugin](./create.mdx#plugin-structure) documentation. If you've made the changes mentioned in [the above section to the scripts](#scripts-in-packagejson) in `package.json`, you should have the correct structure when you run the `prepare` 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 `src` 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 `src` from the final published NPM package.
|
||
|
||
To do that, create the file `.npmignore` with the following content:
|
||
|
||
```bash title=".npmignore"
|
||
/lib
|
||
node_modules
|
||
.DS_store
|
||
.env*
|
||
/*.js
|
||
!index.js
|
||
yarn.lock
|
||
src
|
||
.gitignore
|
||
.eslintrc
|
||
.babelrc
|
||
.prettierrc
|
||
build
|
||
.cache
|
||
.yarn
|
||
uploads
|
||
|
||
# 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
|
||
```
|
||
|
||
---
|
||
|
||
## Publish Plugin
|
||
|
||
This section explains how to publish your plugin to NPM.
|
||
|
||
Before you publish a plugin, you must [create an account on NPM](https://www.npmjs.com/signup).
|
||
|
||
### Step 1: Run Prepare Command
|
||
|
||
Before you publish or update your plugin, make sure to run the `prepare` command [defined earlier](#packagejson-checklist):
|
||
|
||
```bash npm2yarn
|
||
npm run prepare
|
||
```
|
||
|
||
### Step 2: Publish Plugin Package
|
||
|
||
You can publish your package with the following command:
|
||
|
||
```bash
|
||
npm publish
|
||
```
|
||
|
||
If you haven't logged in before with your NPM account, you'll be asked to login first.
|
||
|
||
Your package is then published on NPM and everyone can use it and install it.
|
||
|
||
---
|
||
|
||
## Install Plugin
|
||
|
||
To install your published plugin, run the following command on any Medusa backend project:
|
||
|
||
```bash npm2yarn
|
||
npm install medusa-plugin-custom
|
||
```
|
||
|
||
Where `medusa-plugin-custom` is your plugin's package name.
|
||
|
||
---
|
||
|
||
## Update Plugin
|
||
|
||
If you make changes to your plugin and you want to publish those changes, run the following command to change the NPM version:
|
||
|
||
```bash
|
||
npm version <type>
|
||
```
|
||
|
||
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](https://docs.npmjs.com/cli/v8/commands/npm-version).
|
||
|
||
Then, publish the new update:
|
||
|
||
```bash
|
||
npm publish
|
||
```
|