Medusa Module Links: Relating Data Across Isolated Modules

The first genuine question everyone has after building a Medusa module is: fine, but how do I attach it to a product?

You cannot add a foreign key — that would couple your module to the Product module and defeat the isolation the whole architecture rests on. The answer is a module link: a declared relationship that Medusa stores in its own table and resolves through the query layer.

Defining a link

A brand module, linked to core products:

import BrandModule from "../modules/brand"
import ProductModule from "@medusajs/medusa/product"
import { defineLink } from "@medusajs/framework/utils"

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

linkable is generated from each module's models. This declares a relationship between products and brands — the direction reads as "a product has a brand."

Generate and run the migration:

npx medusa db:migrate

Medusa creates a table holding the pairs. Neither module's schema changes.

Reading across a link

The query service resolves links transparently. Ask for nested fields and it assembles the result across modules:

import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"

export async function GET(req: MedusaRequest, res: MedusaResponse) {
  const query = req.scope.resolve("query")

  const { data: products } = await query.graph({
    entity: "product",
    fields: [
      "id",
      "title",
      "handle",
      "brand.*",            // resolved through the link
      "variants.*",
    ],
    filters: { id: req.params.id },
  })

  res.json({ product: products[0] })
}

You did not join anything. query read the link table, fetched from both modules and stitched the result. It also handles pagination and filtering on either side.

Filtering by the linked entity works the same way:

const { data: products } = await query.graph({
  entity: "product",
  fields: ["id", "title", "brand.name"],
  filters: { brand: { name: "Aurora" } },
})

Writing links

Links are created in workflows using the link management step:

import { createWorkflow, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
import { Modules } from "@medusajs/framework/utils"
import { BRAND_MODULE } from "../modules/brand"

type Input = { product_id: string; brand_id: string }

export const assignBrandWorkflow = createWorkflow(
  "assign-brand",
  (input: Input) => {
    const links = createRemoteLinkStep([
      {
        [Modules.PRODUCT]: { product_id: input.product_id },
        [BRAND_MODULE]: { brand_id: input.brand_id },
      },
    ])

    return new WorkflowResponse(links)
  }
)

Because it is a step, it compensates: if a later step fails, the link is removed. Use dismissRemoteLinkStep to detach.

One-to-one versus list

By default a link is a list — many products to many brands. For a strict one-to-one, say so:

export default defineLink(
  ProductModule.linkable.product,
  {
    linkable: BrandModule.linkable.brand,
    isList: false,
  }
)

Get this right at design time. Changing it later means a data migration, because the shape of the link table changes.

When to use a link versus metadata

The decision that determines whether your data model ages well.

The failure mode is predictable: metadata starts as one field and becomes an untyped, unindexed, unvalidated schema that half the codebase reads with optional chaining. If you would want a database index on it, it belongs in a module.

Practical guidance

Name link files for the pair. product-brand.ts, order-invoice.ts. Someone will need to find them.

Query for exactly the fields you need. brand.* is convenient; on a listing that returns 50 products it fetches more than it should. Ask for brand.name when that is all you render.

Do not copy linked data into your module. Storing brand_name alongside brand_id "for speed" creates a cache you must invalidate. Query across the link.

Remember links are directional in reading, not in truth. You can traverse from either side; the definition order only sets the natural field name.

Read-only links to core data

Links also work in the other direction: exposing your module's data on a core entity without your module knowing anything about it. This is what makes a plugin able to enrich products it did not define.

const { data: products } = await query.graph({
  entity: "product",
  fields: ["id", "title", "reviews.rating", "reviews.body"],
  filters: { "reviews.rating": { $gte: 4 } },
})

Filtering on the linked entity's fields is resolved by the query layer, so a plugin's reviews become a first-class filter on products with no change to the Product module.

Performance of linked queries

Links are resolved by the query layer rather than by a SQL join, which has one practical consequence: a listing that requests deeply nested linked fields issues more work than one that does not.

Guidance that holds up in practice:

• +**Request named fields, not *, on listings.** brand.name where brand.* is not needed.
• +Index the columns you filter on. A link's foreign column in your module should carry an index — model.text().index().
• +Cache listing queries. Category pages with linked data are the classic candidate; see caching.

Detail pages can afford richer projections. Listings, which fan out over dozens of records, cannot.

Deleting linked records

Because links are not foreign keys, the database will not stop you deleting a record something else points at. Cleanup is your responsibility.

Handle it in the workflow that deletes, using dismissRemoteLinkStep so the link goes with the record:

dismissRemoteLinkStep([
  {
    [Modules.PRODUCT]: { product_id: input.product_id },
    [BRAND_MODULE]: { brand_id: input.brand_id },
  },
])

If you delete outside a workflow, add a periodic job that finds links whose targets no longer resolve and removes them. Orphaned links are harmless in the sense that queries skip them, and they accumulate — and an audit that says "12,000 links point at nothing" is an uncomfortable conversation you can avoid with one scheduled job.

Links are the piece that makes module isolation practical rather than theoretical. If a data model is fighting you, we are happy to look.