From 3566bccb765c901c620006c649ab897bcbca0ce0 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 30 Jan 2023 14:11:00 +0200 Subject: [PATCH] docs: added publish plugin documentation (#3137) --- .../advanced/backend/plugins/create.md | 183 ++---------------- .../advanced/backend/plugins/overview.md | 3 +- .../advanced/backend/plugins/publish.md | 160 +++++++++++++++ www/docs/sidebars.js | 5 + 4 files changed, 185 insertions(+), 166 deletions(-) create mode 100644 docs/content/advanced/backend/plugins/publish.md diff --git a/docs/content/advanced/backend/plugins/create.md b/docs/content/advanced/backend/plugins/create.md index 3f8b8a57b5..f70ff779a6 100644 --- a/docs/content/advanced/backend/plugins/create.md +++ b/docs/content/advanced/backend/plugins/create.md @@ -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 -``` - -Where `` 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). --- diff --git a/docs/content/advanced/backend/plugins/overview.md b/docs/content/advanced/backend/plugins/overview.md index ddf8bf2698..74b430230a 100644 --- a/docs/content/advanced/backend/plugins/overview.md +++ b/docs/content/advanced/backend/plugins/overview.md @@ -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) diff --git a/docs/content/advanced/backend/plugins/publish.md b/docs/content/advanced/backend/plugins/publish.md new file mode 100644 index 0000000000..aca5129095 --- /dev/null +++ b/docs/content/advanced/backend/plugins/publish.md @@ -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 +``` + +Where `` 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) \ No newline at end of file diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js index 1678897c08..ed5af1c12f 100644 --- a/www/docs/sidebars.js +++ b/www/docs/sidebars.js @@ -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",