docs: added plugins documentation (#10989)

(Should be merged after the next release) Closes DX-1294
2025-01-27 09:32:53 +00:00
1 parent 0c5f21e893
commit c26ef84cae
@@ -15,7 +15,7 @@ export const metadata = {

 # {metadata.title}

-The `create-medusa-app` CLI tool simplifies the process of creating a new Medusa project and provides an onboarding experience.
+The `create-medusa-app` CLI tool simplifies the process of creating a new Medusa project. It also allows you to setup a [Medusa plugin project](#create-a-medusa-plugin-project).

 <Prerequisites items={[
  {
@@ -206,6 +206,23 @@ npx create-medusa-app@latest [project-name]

      </Table.Cell>
    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+
+        `--plugin`
+
+      </Table.Cell>
+      <Table.Cell>
+
+        Create a [plugin project](#create-a-medusa-plugin-project) instead of a Medusa application. This option is available starting from [Medusa v2.3.0](https://github.com/medusajs/medusa/releases/tag/v2.3.0).
+
+      </Table.Cell>
+      <Table.Cell>
+      
+        `false`
+
+      </Table.Cell>
+    </Table.Row>
  </Table.Body>
 </Table>

@@ -241,6 +258,18 @@ If the database already has the necessary migrations and you don't need the comm

 ---

+## Create a Medusa Plugin Project
+
+The `create-medusa-app` tool can also be used to create a Medusa Plugin Project. You can do that by passing the `--plugin` option:
+
+```bash
+npx create-medusa-app@latest my-plugin --plugin
+```
+
+Learn more about how to create a plugin in [this documentation](!docs!/learn/fundamentals/plugins).
+
+---
+
 ## Troubleshooting

 <DetailsList
@@ -1,6 +1,6 @@
 ---
 sidebar_label: "exec"
-sidebar_position: 6
+sidebar_position: 7
 ---

 import { Table } from "docs-ui"
@@ -0,0 +1,100 @@
+---
+sidebar_label: "plugin"
+sidebar_position: 6
+---
+
+import { Table } from "docs-ui"
+
+export const metadata = {
+  title: `plugin Commands - Medusa CLI Reference`,
+}
+
+# {metadata.title}
+
+Commands starting with `plugin:` perform actions related to [plugin](!docs!/learn/fundamentals/plugins) development.
+
+<Note>
+
+These commands are available starting from [Medusa v2.3.0](https://github.com/medusajs/medusa/releases/tag/v2.3.0).
+
+</Note>
+
+## plugin\:publish
+
+Publish a plugin into the local packages registry. The command uses [Yalc](https://github.com/wclr/yalc) under the hood to publish the plugin to a local package registry. You can then install the plugin in a local Medusa project using the [plugin\:add](#pluginadd) command.
+
+```bash
+npx medusa plugin:publish
+```
+
+---
+
+## plugin\:add
+
+Install the specified plugins from the local package registry into a local Medusa application. Plugins can be added to the local package registry using the [plugin\:publish](#pluginpublish) command.
+
+```bash
+npx medusa plugin:add [names...]
+```
+
+### Arguments
+
+<Table>
+  <Table.Header>
+    <Table.Row>
+      <Table.HeaderCell>Argument</Table.HeaderCell>
+      <Table.HeaderCell>Description</Table.HeaderCell>
+      <Table.HeaderCell>Required</Table.HeaderCell>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>
+      
+      `names`
+      
+      </Table.Cell>
+      <Table.Cell>
+
+      The names of one or more plugins to install from the local package registry. A plugin's name is as specified in its `package.json` file.
+      
+      </Table.Cell>
+      <Table.Cell>
+
+      Yes
+
+      </Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table>
+
+---
+
+## plugin\:develop
+
+Start a development server for a plugin. The command will watch for changes in the plugin's source code and automatically re-publish the changes into the local package registry.
+
+```bash
+npx medusa plugin:develop
+```
+
+---
+
+## plugin\:db\:generate
+
+Generate migrations for all modules in a plugin.
+
+```bash
+npx medusa plugin:db:generate
+```
+
+---
+
+## plugin\:build
+
+Build a plugin before publishing it to NPM. The command will compile an output in the `.medusa/server` directory.
+
+```bash
+npx medusa plugin:build
+```
+
@@ -1,6 +1,6 @@
 ---
 sidebar_label: "start-cluster"
-sidebar_position: 7
+sidebar_position: 8
 ---

 import { Table } from "docs-ui"
@@ -1,6 +1,6 @@
 ---
 sidebar_label: "telemetry"
-sidebar_position: 8
+sidebar_position: 9
 ---

 import { Table } from "docs-ui"
@@ -0,0 +1,21 @@
+import { ChildDocs } from "docs-ui"
+
+export const metadata = {
+  title: `Plugins`,
+}
+
+# {metadata.title}
+
+A plugin is a package of re-usable Medusa customizations, including [modules](!docs!/learn/fundamentals/modules), [workflows](!docs!/learn/fundamentals/workflows), [API routes](!docs!/learn/fundamentals/api-routes), and more.
+
+Plugins are useful if you want to re-use your customizations across Medusa applications, or you want to share those customizations with the community. You publish your plugin to NPM, then install it in a Medusa application to use its features.
+
+<Note>
+
+Learn more about plugins and their difference from modules in [this documentation](!docs!/learn/fundamentals/plugins).
+
+</Note>
+
+## Guides
+
+<ChildDocs showItems={["Guides"]} hideTitle />
@@ -212,7 +212,7 @@ So, the `RestockModuleService` class now has methods like `createRestockSubscrip

 <Note>

-Find all methods generated by the `MedusaService` in [this reference](../../..//service-factory-reference/page.mdx).
+Find all methods generated by the `MedusaService` in [this reference](../../../service-factory-reference/page.mdx).

 </Note>

@@ -330,7 +330,7 @@ You define a link using `defineLink` from the Modules SDK. It accepts three para

 1. The first data model part of the link, which is the Restock Module's `restockSubscription` data model. A module has a special `linkable` property that contain link configurations for its data models. You also specify the field that points to the product variant.
 1. The second data model part of the link, which is the Product Module's `productVariant` data model.
-3. An object of configurations for the module link. By default, Medusa creates a table in the database to represent the link you define. However, in this guide, you only want this link to retrieve the variants associated with a subscription and vice-versa. So, you enable `readOnly` telling Medusa not to create a table for this link.
+3. An object of configurations for the module link. By default, Medusa creates a table in the database to represent the link you define. However, in this guide, you only want this link to retrieve the variants associated with a subscription. So, you enable `readOnly` telling Medusa not to create a table for this link.

 In the next steps, you'll see how this link allows you to retrieve product variants' details when retrieving restock subscriptions.