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
198
www/apps/docs/content/development/modules/publish.md
Normal file
198
www/apps/docs/content/development/modules/publish.md
Normal file
@@ -0,0 +1,198 @@
|
||||
---
|
||||
description: 'Learn how to prepare and publish your custom module to NPM, then how to install it in the Medusa backend.'
|
||||
---
|
||||
|
||||
# How to Publish a Module
|
||||
|
||||
In this document, you'll learn how to prepare and publish your custom module to NPM, then how to install it in the Medusa backend.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
This guide assumes you've already created a custom module. If not, follow [this guide](./create.mdx) first to create a module.
|
||||
|
||||
You also need an [NPM account](https://www.npmjs.com/signup) to publish the module with.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Create an NPM Project
|
||||
|
||||
If your module isn't located in an NPM project already, you must create one first that will hold your module.
|
||||
|
||||
To do that, run the following commands to create a directory and initialize an NPM project in it:
|
||||
|
||||
```bash npm2yarn
|
||||
mkdir my-module
|
||||
npm init
|
||||
```
|
||||
|
||||
You’ll be asked a couple of questions related to your package, such as its name or license. You can keep the default for now or set them right away.
|
||||
|
||||
Once you’re done, you should have a `package.json` created in the directory.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Changes to package.json
|
||||
|
||||
In your `package.json` file, add or update the following fields:
|
||||
|
||||
```json title=package.json
|
||||
{
|
||||
// other fields
|
||||
"main": "dist/index.js",
|
||||
"publishConfig": {
|
||||
"access": "public"
|
||||
},
|
||||
"files": [
|
||||
"dist"
|
||||
],
|
||||
"devDependencies": {
|
||||
"@medusajs/types": "^0.0.2",
|
||||
"cross-env": "^5.2.1",
|
||||
"typescript": "^4.4.4"
|
||||
},
|
||||
"scripts": {
|
||||
"watch": "tsc --build --watch",
|
||||
"prepare": "cross-env NODE_ENV=production npm run build",
|
||||
"build": "tsc --build",
|
||||
},
|
||||
"dependencies": {
|
||||
"@medusajs/modules-sdk": "^0.1.0",
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This adds the necessary dependencies for development and publishing, including the `@medusajs/modules-sdk` package. It also adds the following scripts:
|
||||
|
||||
- `build`: can be used to manually build your module.
|
||||
- `prepare`: can be used to prepare your module for publishing on NPM
|
||||
- `watch`: (optional, for development) can be used to re-build your module whenever any changes occur without having to manually trigger the `build`.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Configure tsconfig.json
|
||||
|
||||
If you don't already have a `tsconfig.json` file, create one in the root of your NPM project with the following content:
|
||||
|
||||
```json title=tsconfig.json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"lib": [
|
||||
"es2020"
|
||||
],
|
||||
"target": "2020",
|
||||
"outDir": "./dist",
|
||||
"esModuleInterop": true,
|
||||
"declaration": true,
|
||||
"module": "commonjs",
|
||||
"moduleResolution": "node",
|
||||
"emitDecoratorMetadata": true,
|
||||
"experimentalDecorators": true,
|
||||
"sourceMap": true,
|
||||
"noImplicitReturns": true,
|
||||
"strictNullChecks": true,
|
||||
"strictFunctionTypes": true,
|
||||
"noImplicitThis": true,
|
||||
"allowJs": true,
|
||||
"skipLibCheck": true,
|
||||
},
|
||||
"include": ["src"],
|
||||
"exclude": [
|
||||
"dist",
|
||||
"./src/**/__tests__",
|
||||
"./src/**/__mocks__",
|
||||
"./src/**/__fixtures__",
|
||||
"node_modules"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
This allows you to use the recommended TypeScript configurations and sets the output directory to `dist`. This is essential for preparing your module for publishing.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Change Module Structure
|
||||
|
||||
To ensure that the files are built from the `src` directory to the `dist` directory, make sure to move the module content to a `src` directory inside the new NPM project.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Publish and Use Module
|
||||
|
||||
This section explains how to publish your module to NPM.
|
||||
|
||||
### Run Prepare Command
|
||||
|
||||
Before you publish or update your module, make sure to run the `prepare` command defined earlier:
|
||||
|
||||
```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 Module 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 Module
|
||||
|
||||
To install your published module, you can run the following command on any Medusa backend project:
|
||||
|
||||
```bash
|
||||
npm install module-name
|
||||
```
|
||||
|
||||
Where `module-name` is the name of your module.
|
||||
|
||||
### Add Module to medusa-config.js
|
||||
|
||||
In `medusa-config.js` on your Medusa backend, add your module to the exported configurations:
|
||||
|
||||
```js title=medusa-config.js
|
||||
module.exports = {
|
||||
// ...
|
||||
modules: {
|
||||
// ...
|
||||
moduleType: {
|
||||
resolve: "<module-name>",
|
||||
options: {
|
||||
// options if necessary
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Where `<module-name>` is the name of your NPM package.
|
||||
|
||||
You can learn more about the available options in the [Create Module documentation](./create.mdx#step-3-reference-module).
|
||||
|
||||
### Update Module
|
||||
|
||||
To update your module 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