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
GitHub
586
www/apps/docs/content/development/plugins/create.mdx
Normal file
586
www/apps/docs/content/development/plugins/create.mdx
Normal file
@@ -0,0 +1,586 @@
|
||||
---
|
||||
description: 'Learn how to create a plugin in Medusa. This guide explains how to develop, configure, and test a plugin.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
import Icons from '@theme/Icon';
|
||||
import LearningPath from '@site/src/components/LearningPath';
|
||||
|
||||
# How to Create a Plugin
|
||||
|
||||
In this document, you’ll learn how to create a plugin and some tips for development. 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.mdx).
|
||||
|
||||
Alternatively, you can follow this recipe to create a plugin with step-by-step guidance.
|
||||
|
||||
<LearningPath pathName="plugin" />
|
||||
|
||||
## Prerequisites
|
||||
|
||||
You must have an existing Medusa project that you want to create the plugin with.
|
||||
|
||||
The recommended way to create a plugin is using the `new` command from Medusa CLI:
|
||||
|
||||
```bash
|
||||
npx @medusajs/medusa-cli@latest new medusa-plugin-custom
|
||||
```
|
||||
|
||||
Where `medusa-plugin-custom` is the name of the plugin you’re creating. In Medusa, plugins are named based on their functionalities.
|
||||
|
||||
By convention, all plugin names start with `medusa` followed by a descriptive name of what the plugin does. For example, the Stripe plugin is named `medusa-payment-stripe`.
|
||||
|
||||
---
|
||||
|
||||
## Changes to package.json
|
||||
|
||||
### Package Name
|
||||
|
||||
By default, your package name in `package.json` will be `medusa-starter-default`. This should instead be the name of your plugin. For example, the Stripe plugin's package name is `medusa-payment-stripe`.
|
||||
|
||||
### Change Dependencies
|
||||
|
||||
A basic Medusa backend installed with the `medusa new` command has dependencies that are necessary for the backend, but not necessary for plugins.
|
||||
|
||||
For example, can remove the dependencies `medusa-fulfillment-manual`, `medusa-payment-manual`, and `medusa-payment-stripe` as they are fulfillment and payment plugins necessary for a Medusa backend, but not for a plugin. The same goes for modules like `@medusajs/cache-inmemory`.
|
||||
|
||||
Additionally, you can remove `@medusajs/medusa-cli` as you don’t need to use the Medusa CLI while developing a plugin.
|
||||
|
||||
You should also add `@medusajs/medusa` as a peer dependency:
|
||||
|
||||
```json
|
||||
"peerDependencies": {
|
||||
"@medusajs/medusa": "YOUR_MEDUSA_VERSION",
|
||||
// other peer dependencies...
|
||||
}
|
||||
```
|
||||
|
||||
Where `YOUR_MEDUSA_VERSION` is the version you're using of the Medusa core package. You should be able to find it under `devDependencies`.
|
||||
|
||||
Once you’re done making these changes, re-run the install command to update your `node_modules` directory:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install
|
||||
```
|
||||
|
||||
Then, make sure to remove the plugins and modules you removed from `medusa-config.js`:
|
||||
|
||||
```js title=medusa-config.js
|
||||
// previously had plugins
|
||||
const plugins = []
|
||||
|
||||
// previously had modules
|
||||
const modules = {}
|
||||
```
|
||||
|
||||
### Changes for Admin Plugins
|
||||
|
||||
If your plugin contains customizations to the admin dashboard, it's recommended to create different `tsconfig` files for backend and admin customizations, then modify the scripts in `package.json` to handle building backend and admin customizations separately.
|
||||
|
||||
:::note
|
||||
|
||||
These changes may already be available in your Medusa project. They're included here for reference purposes.
|
||||
|
||||
:::
|
||||
|
||||
Start by updating your `tsconfig.json` with the following configurations:
|
||||
|
||||
```json title=tsconfig.json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "es2019",
|
||||
"module": "commonjs",
|
||||
"allowJs": true,
|
||||
"checkJs": false,
|
||||
"jsx": "react-jsx",
|
||||
"declaration": true,
|
||||
"outDir": "./dist",
|
||||
"rootDir": "./src",
|
||||
"experimentalDecorators": true,
|
||||
"emitDecoratorMetadata": true,
|
||||
"noEmit": false,
|
||||
"strict": false,
|
||||
"moduleResolution": "node",
|
||||
"esModuleInterop": true,
|
||||
"resolveJsonModule": true,
|
||||
"skipLibCheck": true,
|
||||
"forceConsistentCasingInFileNames": true
|
||||
},
|
||||
"include": ["src/"],
|
||||
"exclude": [
|
||||
"dist",
|
||||
"build",
|
||||
".cache",
|
||||
"tests",
|
||||
"**/*.spec.js",
|
||||
"**/*.spec.ts",
|
||||
"node_modules",
|
||||
".eslintrc.js"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The important changes to note here are the inclusion of the field `"jsx": "react-jsx"` and the addition of `"build"` and `“.cache”` to `exclude`.
|
||||
|
||||
The addition of `"jsx": "react-jsx"` specified how should TypeScript transform JSX, and excluding `build` and `.cache` ensures that TypeScript ignores build and development files.
|
||||
|
||||
Next, create the file `tsconfig.server.json` with the following content:
|
||||
|
||||
```json title=tsconfig.server.json
|
||||
{
|
||||
"extends": "./tsconfig.json",
|
||||
"compilerOptions": {
|
||||
/* Emit a single file with source maps instead of having a separate file. */
|
||||
"inlineSourceMap": true
|
||||
},
|
||||
"exclude": ["src/admin", "**/*.spec.js"]
|
||||
}
|
||||
```
|
||||
|
||||
This is the configuration that will be used to transpile your custom backend code, such as services or entities. The important part is that it excludes `src/admin` as that is where your Admin code will live.
|
||||
|
||||
Then, create the file `tsconfig.admin.json` with the following content:
|
||||
|
||||
```json title=tsconfig.admin.json
|
||||
{
|
||||
"extends": "./tsconfig.json",
|
||||
"compilerOptions": {
|
||||
"module": "esnext"
|
||||
},
|
||||
"include": ["src/admin"],
|
||||
"exclude": ["**/*.spec.js"]
|
||||
}
|
||||
```
|
||||
|
||||
This is the configuration that will be used when transpiling your admin code.
|
||||
|
||||
Finally, update the `build` scripts in your project and add a new `prepare` command:
|
||||
|
||||
```json title=package.json
|
||||
"scripts": {
|
||||
// other scripts...
|
||||
"build": "cross-env npm run clean && npm run build:server && npm run build:admin",
|
||||
"build:server": "cross-env npm run clean && tsc -p tsconfig.json",
|
||||
"build:admin": "cross-env medusa-admin build",
|
||||
"prepare": "cross-env NODE_ENV=production npm run build:server && medusa-admin bundle"
|
||||
}
|
||||
```
|
||||
|
||||
Each of these scripts do the following:
|
||||
|
||||
- `build`: used to build resources for both admin and backend for development. You'll typically use this script during your plugin development.
|
||||
- `build:server`: used to build backend resources for development.
|
||||
- `build:admin`: used to build admin resources for development.
|
||||
- `prepare`: used to build resources for publishing. You'll typically use this script during plugin testing and publishing.
|
||||
|
||||
Furthermore, make sure to add `react` to `peerDependencies` along with `react-router-dom` if you're using it:
|
||||
|
||||
```json title=package.json
|
||||
"peerDependencies": {
|
||||
// other dependencies...
|
||||
"react": "^18.2.0",
|
||||
"react-router-dom": "^6.13.0"
|
||||
}
|
||||
```
|
||||
|
||||
### Delete Irrelevant Files
|
||||
|
||||
If you've installed the Medusa backend using the [create-medusa-app](../../create-medusa-app.mdx) command, you might find files under the `src` sub-directories that aren't necessary for your plugin development. For example, `src/model/onboarding.ts` or migrations under the `src/migrations` directory.
|
||||
|
||||
Make sure to delete these files if you're not using them in your plugin.
|
||||
|
||||
---
|
||||
|
||||
## Plugin Development
|
||||
|
||||
### Plugin Structure
|
||||
|
||||
While developing your plugin, you can create your TypeScript or JavaScript files under the `src` directory. This includes creating services, endpoints, migrations, and other resources.
|
||||
|
||||
However, before you test the changes on a Medusa backend or publish your plugin, you must transpile your files and move them either to a `dist` directory or to the root of the plugin's directory.
|
||||
|
||||
For example, if you have an endpoint in `src/api/index.js`, after running the `build` or `watch` commands [as defined earlier](#recommended-change-scripts), the file should be transpiled into `dist/api/index.js` in your plugin's root. You can alternative transpile them into the `api/index.js` in your plugin's root.
|
||||
|
||||
:::note
|
||||
|
||||
It was previously required to output your files into the root of the plugin's directory (for example, `api/index.js` instead of `dist/api/index.js`). As of v1.8, you can either have your files in the root of the directory or under the `dist` directory.
|
||||
|
||||
:::
|
||||
|
||||
### Development Resources
|
||||
|
||||
This guide doesn't cover how to create different files and components. If you’re interested in learning how to do that, you can check out these guides:
|
||||
|
||||
<DocCardList colSize={6} items={[
|
||||
{
|
||||
type: 'link',
|
||||
href: '/development/entities/create',
|
||||
label: 'Create an Entity',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to create an entity.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/development/services/create-service',
|
||||
label: 'Create a Service',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to create a service.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/development/endpoints/create',
|
||||
label: 'Create an Endpoint',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to create an endpoint.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/development/events/create-subscriber',
|
||||
label: 'Create a Subscriber',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to create a subscriber.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/admin/widgets',
|
||||
label: 'Create an Admin Widget',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to create an admin widget.',
|
||||
badge: {
|
||||
variant: 'orange',
|
||||
children: 'Beta'
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/admin/routes',
|
||||
label: 'Create an Admin UI Route',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to create an admin UI route.',
|
||||
badge: {
|
||||
variant: 'orange',
|
||||
children: 'Beta'
|
||||
}
|
||||
}
|
||||
},
|
||||
]} />
|
||||
|
||||
If you're developing something specific, such as a payment processor plugin, you can follow one of the following guides to learn how to create different services within your plugin.
|
||||
|
||||
<DocCardList colSize={6} items={[
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/carts-and-checkout/backend/add-payment-provider',
|
||||
label: 'Create a Payment Processor',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to create a payment processor.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/carts-and-checkout/backend/add-fulfillment-provider',
|
||||
label: 'Create a Fulfillment Provider',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to create a fulfillment provider.'
|
||||
}
|
||||
},
|
||||
]} />
|
||||
|
||||
<DocCardList colSize={4} items={[
|
||||
{
|
||||
type: 'link',
|
||||
href: '/development/search/create',
|
||||
label: 'Create a Search Service',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to create a search service.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/development/file-service/create-file-service',
|
||||
label: 'Create a File Service',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to create a file service.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/development/file-service/create-file-service',
|
||||
label: 'Create a Notification Service',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to create a notification service.'
|
||||
}
|
||||
},
|
||||
]} />
|
||||
|
||||
### Plugin Options
|
||||
|
||||
Plugins often allow developers that will later use them to provide their own option. For example, you can allow developers to specify the API key of a service you’re integrating.
|
||||
|
||||
Developers that use your plugin will pass options to your plugin in the `plugins` array in `medusa-config.js`:
|
||||
|
||||
```js title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: `medusa-plugin-custom`,
|
||||
options: {
|
||||
name: "My Store",
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
In your plugin's services, you can have access to the option in their constructor. The options are passed as a second parameter to the `constructor` method.
|
||||
|
||||
For example:
|
||||
|
||||
```js title=src/service/my.ts
|
||||
// In a service in your plugin
|
||||
class MyService extends TransactionBaseService {
|
||||
constructor(container, options) {
|
||||
super(container)
|
||||
// options contains plugin options
|
||||
this.name = options.name
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
You can also access the options in your plugin's endpoints. The second parameter that the function declared in `src/api/index.ts` receives is an object including your plugin's configurations.
|
||||
|
||||
For example:
|
||||
|
||||
```js title=src/api/index.ts
|
||||
// in an endpoint in your plugin
|
||||
export default (rootDirectory, options) => {
|
||||
// options contain the plugin options
|
||||
const router = Router()
|
||||
|
||||
router.get("/hello-world", (req, res) => {
|
||||
res.json({
|
||||
message:
|
||||
`Welcome to ${options.name ? options.name : "Medusa"}!`,
|
||||
})
|
||||
})
|
||||
|
||||
return router
|
||||
}
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
Make sure to include in the README of your plugin the options that can be passed to a plugin.
|
||||
|
||||
:::
|
||||
|
||||
### enableUI Plugin Option
|
||||
|
||||
All plugins accept an option named `enableUI`. This option is useful mainly if your plugin contains admin customizations. It allows users to enable or disable admin customizations in the admin dashboard.
|
||||
|
||||
A developer using your plugin can pass the `enableUI` option as part of the plugin's options:
|
||||
|
||||
```js title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: `medusa-plugin-custom`,
|
||||
options: {
|
||||
// other options
|
||||
enableUI: true,
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
If you're passing your plugin options to third-party services, make sure to omit it from the plugin options you receive in your resources, such as services. The `enableUI` option will always be passed as part of your plugin options.
|
||||
|
||||
For example:
|
||||
|
||||
```js title=src/service/test.ts
|
||||
// In a service in your plugin
|
||||
class MyService extends TransactionBaseService {
|
||||
constructor(container, options) {
|
||||
super(container)
|
||||
// options contains plugin options
|
||||
const { enableUI, ...otherOptions } = options
|
||||
// pass otherOptions to a third-party service
|
||||
const client = new Client(otherOptions)
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
`enableUI`'s default value is `false` if not provided by the plugin users. This means that it must be enabled manually in a plugin's option for the customizations to appear in the admin dashboard.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Test Your Plugin
|
||||
|
||||
While you develop your plugin, you’ll need to test it on an actual Medusa backend. This can be done using the [npm link](https://docs.npmjs.com/cli/v8/commands/npm-link) command.
|
||||
|
||||
### Step 1: Build Changes
|
||||
|
||||
<Tabs groupId="plugin-preference">
|
||||
<TabItem value="without-admin" label="Without Admin Customizations" default>
|
||||
|
||||
In the root of your plugin directory, run the `build` command:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="with-admin" label="With Admin Customizations">
|
||||
|
||||
In the root of your plugin directory, run the `prepare` command:
|
||||
|
||||
```bash
|
||||
npm run prepare
|
||||
```
|
||||
|
||||
If the `prepare` script is not available in your project, you can find it in [this section](#changes-for-admin-plugins).
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Step 2: Link Package
|
||||
|
||||
In the root of your plugin directory, run the following command:
|
||||
|
||||
```bash npm2yarn
|
||||
npm link
|
||||
```
|
||||
|
||||
Then, in the directory of the Medusa backend you want to test the plugin on, run the following command:
|
||||
|
||||
```bash npm2yarn
|
||||
npm link medusa-plugin-custom
|
||||
```
|
||||
|
||||
Where `medusa-plugin-custom` is the package name of your plugin.
|
||||
|
||||
### Step 3: Remove Medusa Dependency
|
||||
|
||||
As your plugin has the `@medusajs/medusa` package installed, and the Medusa backend has `@medusajs/medusa` installed as well, this can cause dependency errors.
|
||||
|
||||
To avoid that, remove the `@medusajs` directory from the `node_modules` of your plugin's directory. For Unix-based operating systems you can use the following command:
|
||||
|
||||
```bash
|
||||
rm -rf node_modules/@medusajs
|
||||
```
|
||||
|
||||
### Step 4: Add Plugin to Configurations
|
||||
|
||||
In the `medusa-config.js` file of the Medusa backend you're testing the plugin on, add your custom plugin to the `plugins` array:
|
||||
|
||||
```js
|
||||
const plugins = [
|
||||
// other plugins...
|
||||
{
|
||||
resolve: `medusa-plugin-custom`,
|
||||
options: {
|
||||
// plugin options...
|
||||
// if plugin has admin customizations:
|
||||
enableUI: true,
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
Make sure to change `medusa-plugin-custom` with the name of your plugin. Also, if your plugin has admin customizations, make sure to include the [enableUI](#enableui-plugin-option) option.
|
||||
|
||||
### (Optional) Step 5: Run Migrations
|
||||
|
||||
If your plugin includes migrations, run the following command in the Medusa backend's directory:
|
||||
|
||||
```bash
|
||||
npx medusa migrations run
|
||||
```
|
||||
|
||||
### Step 6: Run the Medusa Backend
|
||||
|
||||
In the directory of the Medusa backend, start the backend with the `dev` command passing it the `--preserve-symlinks` option:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run dev -- -- --preserve-symlinks
|
||||
```
|
||||
|
||||
### Making Changes to the Plugin
|
||||
|
||||
While testing your plugin, if you need to make changes you need to re-install the plugin's dependencies:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install
|
||||
```
|
||||
|
||||
Then, after making the changes, run the steps [one](#step-1-build-changes), [three](#step-3-remove-medusa-dependency), and [six](#step-6-run-the-medusa-backend) mentioned above.
|
||||
|
||||
### Troubleshoot Errors
|
||||
|
||||
#### Error: The class must be a valid service implementation
|
||||
|
||||
Please make sure that your plugin is following the correct structure. If the error persists then please try the following fix:
|
||||
|
||||
```bash npm2yarn
|
||||
cd <BACKEND_PATH>/node_modules/medusa-interfaces
|
||||
npm link
|
||||
cd <BACKEND_PATH>/node_modules/@medusajs/medusa
|
||||
npm link
|
||||
cd <PLUGIN_PATH>
|
||||
rm -rf node_modules/medusa-interfaces
|
||||
rm -rf node_modules/@medusajs/medusa
|
||||
npm link medusa-interfaces
|
||||
npm link @medusajs/medusa
|
||||
npm link
|
||||
cd <BACKEND_PATH>
|
||||
npm link your-plugin
|
||||
```
|
||||
|
||||
Where `<BACKEND_PATH>` is the path to your Medusa backend and `<PLUGIN_PATH>` is the path to your plugin.
|
||||
|
||||
This links the `medusa-interfaces` and `@medusajs/medusa` packages from your `medusa-backend` to your plugin directory and then links your plugin to your `medusa-backend`.
|
||||
|
||||
#### APIs not loading
|
||||
|
||||
If the APIs you added to your Medussa backend are not loading then please try the following steps:
|
||||
|
||||
```bash npm2yarn
|
||||
cd <PLUGIN_PATH>
|
||||
rm -rf node_modules
|
||||
cd <BACKEND_PATH>/node_modules/<PLUGIN_NAME>
|
||||
npm install
|
||||
cd <PLUGIN_PATH>
|
||||
npm run build
|
||||
cd <BACKEND_PATH>
|
||||
npm run start
|
||||
```
|
||||
|
||||
Where `<BACKEND_PATH>` is the path to your Medusa backend, `<PLUGIN_PATH>` is the path to your plugin and `<PLUGIN_NAME>` is the name of your plugin as it is in your plugin `package.json` file.
|
||||
|
||||
---
|
||||
|
||||
## Publish Plugin
|
||||
|
||||
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.
|
||||
|
||||
Please refer to [this guide on required steps to publish a plugin](./publish.mdx).
|
||||
117
www/apps/docs/content/development/plugins/overview.mdx
Normal file
117
www/apps/docs/content/development/plugins/overview.mdx
Normal file
@@ -0,0 +1,117 @@
|
||||
---
|
||||
description: 'Learn what Plugins are and how they are used in Medusa. Plugins are re-usable customizations that can be added to a Medusa backend.'
|
||||
---
|
||||
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
import Icons from '@theme/Icon';
|
||||
import LearningPath from '@site/src/components/LearningPath';
|
||||
|
||||
# Plugins
|
||||
|
||||
In this document, you’ll get an overview of plugins in Medusa, where to find them, and how to install them. If you want to learn how to create a plugin, check out [this guide](create.mdx) instead.
|
||||
|
||||
## Overview
|
||||
|
||||
Medusa was built with flexibility and extendability in mind. All different components and functionalities in Medusa are built with an abstraction layer that gives developers the freedom to choose what services they want to use or how to implement a certain component in their ecommerce store.
|
||||
|
||||
Developers can use plugins to take advantage of this abstraction, flexibility, and extendibility. Plugins allow developers to implement custom features or integrate third-party services into Medusa.
|
||||
|
||||
For example, if you want to use Stripe as a payment processor in your store, then you can install the Stripe plugin on your backend and use it.
|
||||
|
||||
An alternative approach is developing a custom way of handling payment on your ecommerce store. Both approaches are achievable by either creating a plugin or using an existing plugin.
|
||||
|
||||
Plugins run within the same process as the core Medusa backend eliminating the need for extra backend capacity, infrastructure, and maintenance. As a result, plugins can use all other services as dependencies and access the database.
|
||||
|
||||
Plugins can contain customizations to the Medusa backend or the admin dashboard.
|
||||
|
||||
<LearningPath pathName="plugin" />
|
||||
|
||||
---
|
||||
|
||||
## Using Existing Plugins
|
||||
|
||||
### Official Plugins
|
||||
|
||||
Medusa has official plugins that cover different aspects and functionalities such as payment, Content Management System (CMS), fulfillment, and notifications. You can check out the available plugins under the [Plugins section of this documentation](../../plugins/overview.mdx).
|
||||
|
||||
:::tip
|
||||
|
||||
To feature your plugin in our repository, you can send a pull request that adds your plugin into the `packages` directory. Our team will review your plugin and, if approved, will merge the pull request and add your plugin in the repository.
|
||||
|
||||
:::
|
||||
|
||||
### Community Plugins
|
||||
|
||||
You can find community plugins by [searching NPM for the `medusa` or `medusa-plugin` keywords](https://www.npmjs.com/search?q=keywords%3Amedusa%2Cmedusa-plugin).
|
||||
|
||||
You can also check the [Awesome Medusa repository](https://github.com/adrien2p/awesome-medusajs#plugins) for a list of community plugins among other resources.
|
||||
|
||||
---
|
||||
|
||||
## How to Install a Plugin
|
||||
|
||||
To install an existing plugin, in your Medusa backend run the following command:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install <plugin_name>
|
||||
```
|
||||
|
||||
Where `<plugin_name>` is the package name of the plugin. For example, if you’re installing the Stripe plugin `<plugin_name>` is `medusa-payment-stripe`.
|
||||
|
||||
### Plugin Configuration
|
||||
|
||||
If you’re installing an official plugin from the Medusa repository, you can find in its `README.md` file a list of configurations that are either required or optional. You can also refer to the documentation related to that plugin for more details on how to install, configure, and use it.
|
||||
|
||||
For community plugins, please refer to the installation instructions of that plugin to learn about any required configurations.
|
||||
|
||||
### enableUI Plugin Option
|
||||
|
||||
All plugins accept an option named `enableUI`. This option allows you to disable admin customizations from appearing in the admin dashboard.
|
||||
|
||||
:::note
|
||||
|
||||
`enableUI`'s default value is `false` if not provided by the plugin users. This means that it must be enabled manually in a plugin's configuration for the customizations to appear in the admin dashboard.
|
||||
|
||||
:::
|
||||
|
||||
You can set the `enableUI` value by passing it as part of the plugin's configurations:
|
||||
|
||||
```js title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: `medusa-plugin-custom`,
|
||||
options: {
|
||||
// other options
|
||||
enableUI: true,
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Custom Development
|
||||
|
||||
Developers can create plugins and reuse them across different Medusa backends. They can also share them with the community to help out other developers.
|
||||
|
||||
<DocCardList colSize={6} items={[
|
||||
{
|
||||
type: 'link',
|
||||
href: '/development/plugins/create',
|
||||
label: 'Create a Plugin',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to create plugins in Medusa.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/development/plugins/publish',
|
||||
label: 'Publish a Plugin',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to publish a plugin to NPM.'
|
||||
}
|
||||
},
|
||||
]} />
|
||||
182
www/apps/docs/content/development/plugins/publish.mdx
Normal file
182
www/apps/docs/content/development/plugins/publish.mdx
Normal file
@@ -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