asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: added publish plugin documentation (#3137)

Browse Source
This commit is contained in:
Shahed Nasser
2023-01-30 14:11:00 +02:00
committed by GitHub
parent cf89624747
commit 3566bccb76
4 changed files with 185 additions and 166 deletions
Download Patch File Download Diff File Expand all files Collapse all files

183
docs/content/advanced/backend/plugins/create.md
View File

@@ -1,11 +1,11 @@
---
description: 'Learn how to create a plugin in Medusa. This guide explains how to develop, configure, test, and publish the plugins.'
description: 'Learn how to create a plugin in Medusa. This guide explains how to develop, configure, and test a plugin.'
addHowToData: true
---
# How to Create a Plugin
In this document, you’ll learn how to create a plugin and publish it. 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](overview.md).
In this document, you’ll learn how to create a plugin and some tips for develoment. 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](overview.md).
## Prerequisites
@@ -39,10 +39,6 @@ By convention, all plugin names start with `medusa` followed by a descriptive na
## Changes to package.json
### Rename Project Name
Update the `name` field in the `package.json` file to the name of your plugin. This should be the same name that you chose when running the `medusa new` command.
### Change Dependencies
A basic Medusa server installed with the `medusa new` command has dependencies similar to this:
@@ -67,7 +63,7 @@ A basic Medusa server installed with the `medusa new` command has dependencies s
For a plugin, some dependencies are not necessary. You can remove the packages `medusa-fulfillment-manual`, `medusa-payment-manual`, and `medusa-payment-stripe` as they are fulfillment and payment plugins necessary for a Medusa server, but not for a plugin.
Additionally, you remove `@medusajs/medusa-cli` as you don’t need to use the Medusa CLI while developing a plugin.
Additionally, you can remove `@medusajs/medusa-cli` as you don’t need to use the Medusa CLI while developing a plugin.
Once you’re done making these changes, re-run the install command to update your `node_modules` directory:
@@ -75,65 +71,27 @@ Once you’re done making these changes, re-run the install command to update yo
npm install
```
This section includes recommended changes to your `package.json`. You can skip any of these changes if you don’t find them necessary to your plugin.
### Recommended: Change scripts
It's recommended to remove the `seed` and `start` scripts from your `package.json` as they aren't necessary for plugin development.
Furthermore, it's recommended to change the `build` command and add a new `watch` command:
```json title=package.json
"scripts": {
"build": "babel src --out-dir . --ignore **/__tests__ --extensions \".ts,.js\"",
"watch": "babel -w src --out-dir . --ignore **/__tests__ --extensions \".ts,.js\""
}
```
The change to the `build` command ensures that the built files are placed as explained in the [plugin structure section](#plugin-structure). The `watch` command makes the [testing of the plugin](#test-your-plugin) easier.
:::caution
If you don't make changes to the `build` and `watch` commands, please be aware of the [expected plugin structure](#plugin-structure).
:::
A basic Medusa installation comes with the following scripts:
```json title=package.json
"scripts": {
"seed": "medusa seed -f ./data/seed.json",
"build": "babel src --out-dir . --ignore **/__tests__ --extensions \".ts,.js\"",
"start": "medusa develop"
}
```
The `seed` and `start` scripts aren't necessary for plugin development so you can remove them.
It’s also recommended to add the `watch` script that automatically compiles your files if they are changed:
```json title=package.json
"watch": "babel -w src --out-dir . --ignore **/__tests__ --extensions \".ts,.js\""
```
This is helpful when testing the plugin.
:::note
Testing the plugin is covered in a [later section](#test-your-plugin).
:::
Another recommended script is the `prepare` script that builds your files under a “production” environment:
```json title=package.json
"prepare": "cross-env NODE_ENV=production npm run build"
```
You would typically run this script before publishing your plugin.
This script requires installing the package `cross-env` as a development dependency:
```bash npm2yarn
npm install --save-dev cross-env
```
### Recommended: Change Basic Info
`package.json` holds information that further describes the package or the author that created the package. It is recommended to make the following changes:
- `description`: Change this to a sentence that describes what your plugin does.
- `author`: Your name and email.
- `repository`: The repository that holds your plugin’s codebase.
- `keywords`: This should hold the keywords that are related to your plugin. It’s recommended that all plugins use the keywords `medusa-plugin` or `medusa`.
---
## Develop your Plugin
@@ -355,116 +313,11 @@ It is safe to ignore any `cross-env: command not found` error you may receive.
---
## 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
#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
Once you’re done developing your plugin you can publish the package on NPM’s registry so that other developers can benefit from it and use it.
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.
Before you publish a plugin, you must [create an account on NPM](https://www.npmjs.com/signup).
### Prepare Plugin
Before you publish or update your plugin, make sure to run the `prepare` command [defined earlier](#recommended-change-scripts):
```bash npm2yarn
npm run prepare
```
### Login
In your terminal, log in with your NPM account:
```bash
npm login
```
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:
```bash
npm publish
```
Your package is then published on NPM and everyone can use it and install it.
### Update Plugin
To update your plugin at a later point, you can 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
```
---
## Add Plugin to Medusa’s Repository
All officially-supported plugins are available in the [`packages` directory of the Medusa GitHub repository](https://github.com/medusajs/medusa/tree/master/packages).
If you’re interested in adding your plugin, you need to create a new pull request (PR) where you add your plugin inside the `packages` directory. Our team will then review your plugin, and if it’s approved the PR will be merged and your plugin will be available on Medusa’s repository.
:::note
Before contributing to the Medusa repository, please check out the [contribution guidelines](https://github.com/medusajs/medusa/blob/master/CONTRIBUTING.md).
:::
---
## Install a Plugin
To install any published plugin, you can run the following command on any Medusa server project:
```bash npm2yarn
npm install medusa-plugin-custom
```
Please refer to [this guide on required steps to publish a plugin](./publish.md).
---

3
docs/content/advanced/backend/plugins/overview.md
View File

@@ -58,5 +58,6 @@ For community plugins, please refer to the installation instructions of that plu
## See Also
- [Create your own plugin](create.md)
- [Create a plugin](create.md)
- [Publish a plugin](publish.md)
- [Create a fulfillment provider](../shipping/add-fulfillment-provider.md) or a [payment provider](../payment/how-to-create-payment-provider.md)

160
docs/content/advanced/backend/plugins/publish.md Normal file
View File

@@ -0,0 +1,160 @@
---
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
---
# 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](./create.md).
---
## Prepare the 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 server.
- `medusa-plugin-other`: For any other type of plugin.
### Scripts in package.json
Make sure you add the `publish` command to your `scripts` field and make the following change to the `build` command:
```json title=package.json
"build": "babel src --out-dir . --ignore **/__tests__ --extensions \".ts,.js\"",
"prepare": "cross-env NODE_ENV=production npm run build"
```
The `build` command ensures that the plugin's built files are placed as explained in the [plugin structure](./create.md#plugin-structure) section of the Create Plugin documentation.
The `prepare` command facilitates your publishing process. You would typically run this script before publishing your plugin.
This new script requires installing the package `cross-env` as a development dependency:
```bash npm2yarn
npm install --save-dev cross-env
```
### Plugin Structure
Make sure your plugin's structure is as described in the [Create Plugin](./create.md#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
# 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).
### Prepare Plugin
Before you publish or update your plugin, make sure to run the `prepare` command [defined earlier](#packagejson-checklist):
```bash npm2yarn
npm run prepare
```
### Login
In your terminal, log in with your NPM account:
```bash
npm login
```
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:
```bash
npm publish
```
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:
```bash npm2yarn
npm install medusa-plugin-custom
```
### Update Plugin
To update your plugin at a later point, you can 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
```
---
## See Also
- [Available official plugins](https://github.com/medusajs/medusa/tree/master/packages)

5
www/docs/sidebars.js
View File

@@ -399,6 +399,11 @@ module.exports = {
id: "advanced/backend/plugins/create",
label: "Create a Plugin"
},
{
type: "doc",
id: "advanced/backend/plugins/publish",
label: "Publish a Plugin"
},
{
type: "doc",
id: "advanced/backend/migrations/index",