docs: documentation changes for release (#4300)
* docs: added manage reservations user guide (#4290) * docs: added manage reservations user guide * removed feature flag details * docs: added how-to for custom reservations (#4292) * docs: added how-to for custom reservations * eslint fixes * docs: added product module documentation (#4287) * docs: added product module documentation * added details about optional environment variables * small fixes * Remove reference link * added example usages * added link to sample project * address PR feedback * docs: moved product module guide + added product module tabs (#4307) * added product module tab * adjust design of badge * docs: added onboarding features (#4168) * added marketplace page * added subscription roadmap * added rating for onboarding * added learning path components * small fixes * fix build error * fix eslint errors * change roadmaps to recipes * small change in text * optimize learning path and notifications * fix tracking usage * fix eslint errors * added enter/exit animation * allow starting a path using a query parameter * fix gap between notifications * address vercel comments * fixed links issue * changed create-medusa-app docs steps * move troubleshooting section * improved tracking across docs * fix build errors * remove console * added a note about `boilerplate` option * added troubleshooting section for eagain * added invite option in cli reference * added track event for finished onboarding * update boilerplate option name * redesigned learning path component * docs: added how to create widget docs (#4318) * docs: added how to create widget docs * remove development guide * added types * docs: added details about createCustomAdminHooks (#4288) * docs: added details about createCustomAdminHooks * small improvement * added missing import * small changes * docs: added onboarding guide (#4320) * docs: added how to create widget docs * remove development guide * docs: added onboarding guide * added types * added recipes link * small adjustments * fixed eslint errors * styling fixes * change to singular product module * updated the what's new section * shorten down medusa react card * updated tailwind configurations * fix build error * fix newspaper icon * style fixes * change modal shadow * fix color of line numbers * fix code fade color * docs: updated admin documentations * eslint fixes * text changes * added a note about beta version * remove empty object argument * remove demo repo url * fix selection color for code headers * general fixes * fix eslint error * changed code theme * added preparation step * changes regarding beta version * Update docs/content/modules/products/serverless-module.md Co-authored-by: Riqwan Thamir <rmthamir@gmail.com> * Update docs/content/modules/products/serverless-module.md Co-authored-by: Riqwan Thamir <rmthamir@gmail.com> --------- Co-authored-by: Riqwan Thamir <rmthamir@gmail.com> Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com>
This commit is contained in:
Shahed Nasser
GitHub
@@ -0,0 +1,196 @@
|
||||
---
|
||||
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 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 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` command to your `scripts` field and make the following change to the `build` command:
|
||||
|
||||
```json title=package.json
|
||||
"scripts": {
|
||||
// other scripts...
|
||||
"build": "cross-env npm run clean && tsc",
|
||||
"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.mdx#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
|
||||
```
|
||||
|
||||
</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 `publish` command to your `scripts` field and make the following change to the `build` command:
|
||||
|
||||
```json title=package.json
|
||||
"scripts": {
|
||||
// other scripts...
|
||||
"build": "tsc -p ./tsconfig.server.json && medusa-admin bundle",
|
||||
"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.mdx#plugin-structure) section of the Create Plugin documentation, and bundles the admin customizations.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
</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
|
||||
|
||||
# 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).
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
### 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 backend 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
|
||||
```
|
||||
Reference in New Issue
Block a user