Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 33 ยท Customizing the Backend

Module Links

Connect your custom data to Products and Customers without breaking module isolation: defineLink, list links, extra columns, link.create and querying through links.

Medusa modules are isolated: the Product module knows nothing about your custom Review module, and your Review module must not reach into the product tables. Yet a storefront wants to show a product together with its reviews. Module links solve this. A link is a small, separate record that says "this product is connected to that review", stored outside both modules.

In this lesson you learn how defineLink declares a connection, how list links and extra columns work, how to create and remove links, how to read data through them, and why Medusa goes to this trouble. The real Medusa code is read-only here; two runnable stand-ins model a link table and a cross-module join in memory so you can see what the framework does for you.

Suppose you build a brand module with a Brand model, and each product belongs to one brand. The tempting design is a brand_id column on the product table. Medusa does not allow that, for the reasons in Architecture: Modules, Workflows and the Container: modules own their tables, so you cannot add columns to another module's data model, and you want to be able to swap or upgrade modules independently.

Instead, a link is stored in its own link table with one column for each side, for example product_id and brand_id. Neither module's table changes. The link table belongs to neither module; Medusa creates it for you from the link definition and migrates it with medusa db:migrate.

flowchart LR
    P["Product module<br/>product table"] --- L["Link table<br/>product_id, brand_id"]
    L --- B["Brand module<br/>brand table"]

The link table sits between two modules, so neither one needs to know the other's schema.

A link is defined in a file under src/links/. You pass two "linkables". Every module exposes linkable objects for its models, and the framework exposes helpers to build the definition. The code below is real Medusa code and is read-only on this site.

TypeScript
// src/links/product-brand.ts
import { defineLink } from "@medusajs/framework/utils"
import ProductModule from "@medusajs/medusa/product"
import BrandModule from "../modules/brand"

export default defineLink(
  ProductModule.linkable.product,
  BrandModule.linkable.brand
)

By default a link is one-to-one. Marking one side as a list says that many records of that model can attach to the same record on the other side. For example, to say that one product has many reviews, mark the review side as a list:

TypeScript
export default defineLink(
  ProductModule.linkable.product,
  {
    linkable: ReviewModule.linkable.review,
    isList: true, // one product, many reviews
  }
)

The word "list" always describes the side it is attached to: here the review side is a list, so a product links to many reviews.

After adding or changing a link file, run npx medusa db:migrate. Migrations create the link table. Because the table name is derived from the two modules and models, treat the name as an implementation detail and use the link API instead of raw SQL.

Extra columns

Sometimes the relationship itself carries data: when was the product assigned to the campaign, who approved it, with what priority? A link can declare extra columns that live on the link table:

TypeScript
export default defineLink(
  ProductModule.linkable.product,
  CampaignModule.linkable.campaign,
  {
    database: {
      extraColumns: {
        priority: { type: "integer", defaultValue: "0" },
        note: { type: "text", nullable: true },
      },
    },
  }
)

Supply those values when you create the link, as shown next. Keep extra columns small and relationship-specific. If the extra data has its own life (a review has a rating, a body and an author), it belongs in a module's data model, not in link columns.

You work with links through the link service in the container. The keys of each object are module names, and the values name the id column of that module's record. This is real, read-only code:

TypeScript
import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils"
import { BRAND_MODULE } from "../modules/brand"

const link = container.resolve(ContainerRegistrationKeys.LINK)

await link.create({
  [Modules.PRODUCT]: { product_id: "prod_01" },
  [BRAND_MODULE]: { brand_id: "brand_01" },
  data: { /* values for extra columns, if any */ },
})

await link.dismiss({
  [Modules.PRODUCT]: { product_id: "prod_01" },
  [BRAND_MODULE]: { brand_id: "brand_01" },
})

create connects two records; dismiss removes the connection but leaves both records intact. Deleting a record in a module does not delete the other side. Inside a workflow, use the matching steps (createRemoteLinkStep, dismissRemoteLinkStep) so that linking is rolled back if a later step fails (Workflows and Steps).

For a one-to-one link, creating a second link for the same record is an error in the framework. Your own code should check or dismiss first when "replace the brand" is the intent.

Links shine when you read. With Query you ask for a product and name the linked entity in the field list. This is real code, read-only here:

TypeScript
const query = container.resolve(ContainerRegistrationKeys.QUERY)

const { data } = await query.graph({
  entity: "product",
  fields: ["id", "title", "brand.*"],
  filters: { id: "prod_01" },
})
// data[0].brand is the linked Brand record

Query asks the Product module for products, finds their link rows, asks the Brand module for those brands, and stitches the result together. Query: Fields, Filters and Pagination covers the details. Each hop is a separate query, so selecting linked data you do not need costs extra work; ask only for the fields you display.

There is a lighter-weight variant for cases where you only need to read across modules and want no link table: a read-only link. It points a field already stored in one module (such as a product_id string on your custom record) at another module's model, so Query can follow it, but nothing is stored or maintained by the framework. Because there is no link row, link.create does not apply to it. Use a normal link when the relationship should be managed, and a read-only link when your data already holds the id and you only want to read through it.

The real link service persists rows in Postgres. This stand-in models the same contract: a pair of ids, an optional extra payload, a uniqueness rule for one-to-one sides, and create / dismiss / list operations. It is not Medusa's code.

JS A link table with create, dismiss and a one-to-one rule

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that dismissing a link removes only the pair. The review record itself would still exist in its own module.

Two "modules" below hold their own arrays and know nothing about each other. A small graph function joins them through the link table, the way Query does, and shows why selecting fewer fields and fewer relations is cheaper.

JS A Query-like join across isolated modules

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second call needed two module queries instead of one. The real Query also batches by ids rather than looping per product, which is why asking for linked data stays practical even for pages with many products.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does Medusa use a link table instead of adding a brand_id column to the product table?

    Isolation is the point. The Product module's schema stays unchanged, and your module can be developed, replaced or upgraded independently.
  2. 2. What does link.dismiss do?

    Dismissing removes only the link row. The records in their own modules stay.
  3. 3. A product should have many reviews. Which definition expresses that?

    A list side allows many records to attach to a single record on the other side. The default link is one-to-one.
  4. 4. When is extra-column data on a link the right choice?

    Extra columns suit small, relationship-specific values. Data with its own lifecycle belongs in a module's data model.

Summary

  • Links connect records from different modules through a separate link table, so module schemas stay untouched.
  • defineLink in src/links/ declares the connection; isList: true marks a side that can hold many records.
  • Extra columns store small relationship-specific values on the link.
  • link.create and link.dismiss manage connections; in workflows use the remote-link steps so they can be rolled back.
  • Query follows links with fields like brand.*; each hop is a module query, so request only what you need.
  • Read-only links let Query follow an id you already store, with no link table to manage.

Next: Workflows and Steps