docs: create docs workspace (#5174)
* docs: migrate ui docs to docs universe * created yarn workspace * added eslint and tsconfig configurations * fix eslint configurations * fixed eslint configurations * shared tailwind configurations * added shared ui package * added more shared components * migrating more components * made details components shared * move InlineCode component * moved InputText * moved Loading component * Moved Modal component * moved Select components * Moved Tooltip component * moved Search components * moved ColorMode provider * Moved Notification components and providers * used icons package * use UI colors in api-reference * moved Navbar component * used Navbar and Search in UI docs * added Feedback to UI docs * general enhancements * fix color mode * added copy colors file from ui-preset * added features and enhancements to UI docs * move Sidebar component and provider * general fixes and preparations for deployment * update docusaurus version * adjusted versions * fix output directory * remove rootDirectory property * fix yarn.lock * moved code component * added vale for all docs MD and MDX * fix tests * fix vale error * fix deployment errors * change ignore commands * add output directory * fix docs test * general fixes * content fixes * fix announcement script * added changeset * fix vale checks * added nofilter option * fix vale error
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
19c5d5ba36
commit
fa7c94b4cc
3209 files changed
+32188
-31018
No files matched your search
@@ -0,0 +1,182 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
Reference in new issue
Block a user