docs: general fixes and improvements (#7918)

* docs improvements and changes * updated module definition * modules + dml changes * fix build * fix vale error * fix lint errors * fixes to stripe docs * fix condition * fix condition * fix module defintion * fix checkout * disable UI action * change oas preview action * flatten provider module options * fix lint errors * add module link docs * pr comments fixes * fix vale error * change node engine version * links -> linkable * add note about database name * small fixes * link fixes * fix response code in api reference * added migrations step
2024-07-04 17:26:03 +03:00
parent 32982e708a
commit 964927b597
149 changed files with 1676 additions and 3008 deletions
@@ -0,0 +1,128 @@
+export const metadata = {
+  title: `${pageNumber} Module Link`,
+}
+
+# {metadata.title}
+
+In this chapter, you’ll learn what a module link is.
+
+<Note type="soon" title="In Development">
+
+Module links are in active development.
+
+</Note>
+
+## What is a Module Link?
+
+A module link forms an association between two data models of different modules, while maintaining module isolation.
+
+You can then retrieve data across the linked modules, and manage their linked records.
+
+---
+
+## Prerequisite: isQueryable Configuration
+
+Before you define a module link, you must enable the `isQueryable` configuration of the module.
+
+For example:
+
+```js
+module.exports = defineConfig({
+  // ...
+  modules: {
+    helloModuleService: {
+      resolve: "./modules/hello",
+      definition: {
+        isQueryable: true,
+      },
+    },
+  },
+})
+```
+
+---
+
+## How to Define a Module Link?
+
+### 1. Create Link File
+
+Links are defined in a TypeScript or JavaScript file under the `src/links` directory. The file defines the link using the `defineLink` function imported from `@medusajs/utils` and exports it.
+
+For example:
+
+export const highlights = [
+  ["6", "linkable", "Special `linkable` property that holds the linkable data models of `HelloModule`."],
+  ["7", "linkable", "Special `linkable` property that holds the linkable data models of `ProductModule`."],
+]
+
+```ts title="src/links/hello-product.ts" highlights={highlights}
+import HelloModule from "../modules/hello"
+import ProductModule from "@medusajs/product"
+import { defineLink } from "@medusajs/utils"
+
+export default defineLink(
+  HelloModule.linkable.myCustom,
+  ProductModule.linkable.product
+)
+```
+
+The `defineLink` function accepts as parameters the link configurations of each module's data model. A module has a special `linkable` property that holds these configurations for its data models.
+
+In this example, you define a module link between the `hello` module's `MyCustom` data model and the Product Module's `Product` data model.
+
+### 2. Run Migrations
+
+Medusa stores links as pivot tables in the database, so you must run migrations after defining a link:
+
+```bash
+npx medusa migrations run
+```
+
+---
+
+## Define a List Link
+
+By default, the defined link establishes a one-to-one relation: a record of a data model is linked to one record of the other data model.
+
+To specify that a data model can have multiple of its records linked to the other data model's record, use the `isList` option.
+
+For example:
+
+```ts
+import HelloModule from "../modules/hello"
+import ProductModule from "@medusajs/product"
+import { defineLink } from "@medusajs/utils"
+
+export default defineLink(
+  {
+    model: HelloModule.linkable.myCustom,
+    isList: true
+  },
+  ProductModule.linkable.product
+)
+```
+
+In this case, you pass an object of configuration as a parameter rather than the linked model. The object accepts the following properties:
+
+- `model`: The data model to link.
+- `isList`: Whether multiple records can be linked to one record of the other data model.
+
+In this example, a record of `product` can be linked to more than one record of `myCustom`.
+
+---
+
+## Extend Data Models with Module Links
+
+Module links are most useful when you want to add properties to a data model of another module.
+
+For example, to add custom properties to the `Product` data model of the Product Module, you:
+
+1. Create a module.
+2. Create in the module a data model that holds the custom properties you want to add to the `Product` data model.
+2. Define a module link that links your module to the Product Module.
+
+Then, in the next chapters, you'll learn how to:
+
+- Link each product to a record of your data model.
+- Retrieve your data model's properties when you retrieve products.
+