4.2.4. Module Link

In this chapter, you’ll learn what a module link is.

In Development

Module links are in active development.

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.

Use module links when
  • You want to create a relation between data models from different modules.
Don't use module links if
  • You want to create a relationship between data models in the same module. Use data model relationships instead.

Prerequisite: isQueryable Configuration#

Before you define a module link, you must enable the isQueryable configuration of the module.

For example:

1import { HELLO_MODULE } from "./src/modules/hello"2// ...3
4module.exports = defineConfig({5  // ...6  modules: {7    [HELLO_MODULE]: {8      resolve: "./modules/hello",9      definition: {10        isQueryable: true,11      },12    },13  },14})

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:

src/links/hello-product.ts
1import HelloModule from "../modules/hello"2import ProductModule from "@medusajs/product"3import { defineLink } from "@medusajs/utils"4
5export default defineLink(6  HelloModule.linkable.myCustom,7  ProductModule.linkable.product8)

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:

npx medusa migrations run

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:

1import HelloModule from "../modules/hello"2import ProductModule from "@medusajs/product"3import { defineLink } from "@medusajs/utils"4
5export default defineLink(6  {7    linkable: HelloModule.linkable.myCustom,8    isList: true9  },10  ProductModule.linkable.product11)

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.


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.
  3. 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.
Was this chapter helpful?