a74c900ab1
* docs: add documentation for migration generate cli tool * changed migrations details in marketplace recipe * added generated oas files to action * vale + lint fixes * don't import from src in medusa-config.js * fix generate command in recipe * fix module name
144 lines
4.0 KiB
Plaintext
144 lines
4.0 KiB
Plaintext
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.
|
||
|
||
<Note title="Use module links when" type="success">
|
||
|
||
- You want to create a relation between data models from different modules.
|
||
|
||
</Note>
|
||
|
||
<Note title="Don't use module links if" type="error">
|
||
|
||
- You want to create a relationship between data models in the same module. Use data model relationships instead.
|
||
|
||
</Note>
|
||
|
||
---
|
||
|
||
## Prerequisite: isQueryable Configuration
|
||
|
||
Before you define a module link, you must enable the `isQueryable` configuration of the module.
|
||
|
||
For example:
|
||
|
||
```js
|
||
import { HELLO_MODULE } from "./src/modules/hello"
|
||
// ...
|
||
|
||
module.exports = defineConfig({
|
||
// ...
|
||
modules: {
|
||
[HELLO_MODULE]: {
|
||
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(
|
||
{
|
||
linkable: HelloModule.linkable.myCustom,
|
||
isList: true,
|
||
},
|
||
ProductModule.linkable.product
|
||
)
|
||
```
|
||
|
||
In this case, you pass an object of configuration as a parameter instead. The object accepts the following properties:
|
||
|
||
- `linkable`: The data model's link configuration.
|
||
- `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.
|
||
|