774d04da48
* docs: fix keys passed to remoteLink.create and remoteLink.dismiss * updated hello module name + clarified note * added details about module link directions * fix lint errors
143 lines
4.3 KiB
Plaintext
143 lines
4.3 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>
|
||
|
||
---
|
||
|
||
## 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(
|
||
ProductModule.linkable.product,
|
||
HelloModule.linkable.myCustom
|
||
)
|
||
```
|
||
|
||
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. Sync Links
|
||
|
||
Medusa stores links as pivot tables in the database. So, to reflect your link in the database, run the `links sync` command:
|
||
|
||
```bash
|
||
npx medusa links sync
|
||
```
|
||
|
||
Use this command whenever you make changes to your links. For example, run this command if you remove your link definition file.
|
||
|
||
---
|
||
|
||
## 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(
|
||
ProductModule.linkable.product,
|
||
{
|
||
linkable: HelloModule.linkable.myCustom,
|
||
isList: true,
|
||
}
|
||
)
|
||
```
|
||
|
||
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.
|
||
|
||
---
|
||
|
||
## Set Delete Cascades on Link
|
||
|
||
To enable delete cascade on a link so that when a record is deleted, its linked records are also deleted, pass the `deleteCascades` property in the object passed to `defineLink`.
|
||
|
||
For example:
|
||
|
||
```ts
|
||
import HelloModule from "../modules/hello"
|
||
import ProductModule from "@medusajs/product"
|
||
import { defineLink } from "@medusajs/utils"
|
||
|
||
export default defineLink(
|
||
ProductModule.linkable.product,
|
||
{
|
||
linkable: HelloModule.linkable.myCustom,
|
||
deleteCascades: true,
|
||
}
|
||
)
|
||
```
|
||
|
||
In this example, when a product is deleted, its linked `myCustom` record is also deleted. |