Checkpoint Module Links

Before proceeding, test your understanding:

1. Why do we use module links instead of directly importing from another module?

   Module links maintain module isolation - modules don’t depend on each other’s code. The Brand Module doesn’t import Product entities, and Product Module doesn’t import Brand entities. This prevents circular dependencies and allows modules to be developed, tested, and deployed independently. Links are managed by Medusa’s linking layer, not by direct module-to-module references.

2. What does isList: true mean in a link definition?

   isList: true means “one brand can have many products”. Without it (or with isList: false), the relationship would be one-to-one. In our case, we want one brand (e.g., “Nike”) to link to multiple products (shoes, shirts, etc.), so we use isList: true.

3. What is the purpose of BrandModule.linkable.brand?

   linkable is a configuration object exported from each module that declares which entities can be linked to. BrandModule.linkable.brand tells Medusa “the Brand entity in the Brand Module can be used in links”.

4. Why do we put links in src/links directory and not inside a module?

   Links are separate from modules to emphasize module independence. A link is a relationship managed by Medusa’s linking layer, not by either module. Keeping links in a separate directory makes it clear that they’re infrastructure concerns, not business logic. It also makes it easier to see all relationships in your application at a glance.

Implementation Check

Let me verify your implementation. Please share the following:

1. Brand Module Linkable Configuration

Show me your src/modules/brand/index.ts file.

Key things to check:

• Not done: Exports module with Module()
• Not done: Module has service property pointing to BrandService
• Not done: Uses Modules.BRAND constant for module name (or string “brand”)

2. Brand Module Constants

Show me if you created src/modules/brand/types/index.ts for module constants.

Key things to check:

• Not done: Exports MODULE_NAME = "brand"
• Not done: Exports Modules.BRAND constant (if using Modules enum)

Note: You can also define the constant directly in index.ts or use a string literal.

3. Link Definition File

Show me your src/links/brand-product.ts file.

Key things to check:

• Not done: Imports defineLink from “@medusajs/framework/utils”
• Not done: Imports Modules from “@medusajs/framework/utils” (for ProductModule reference)
• Not done: Imports BrandModule from “../modules/brand”
• Not done: Calls defineLink() with two arguments
• Not done: First argument configures product side:

  typescriptCopy

  {
    linkable: ProductModule.linkable.product,
    isList: true,
  }

• Not done: Second argument is BrandModule.linkable.brand
• Not done: File has default export: export default defineLink(...)

4. Database Sync

Run the database sync command:

Expected output: Should show that link was created successfully without errors. You should see output mentioning the brand-product relationship.

5. Build Test

Run build to ensure no TypeScript errors:

Expected output: Build should succeed without errors related to links or modules.

Common Issues

“Link sync failed” or “Cannot resolve module”

Symptom: db:sync-links command fails

Cause: Module not registered in medusa-config.ts, or server not recognizing the module

Fix:

1. Verify brand module is in medusa-config.ts modules array
2. Restart dev server: npm run dev
3. Try sync again: npx medusa db:sync-links

Testing Checklist

Verify each of these steps:

• Not done: Link file created in src/links/ directory
• Not done: db:sync-links command succeeds
• Not done: Build succeeds without TypeScript errors
• Not done: Dev server starts without link-related errors

Architecture Understanding

At this point, you should understand:

Module Isolation:

Why module links matter:

• Flexibility: Modules can be added/removed without breaking others
• Testability: Test Brand Module without needing Product Module
• Scalability: Modules can be extracted into separate packages
• Versioning: Modules can evolve independently

Next Steps

Once this checkpoint passes:

1. Module Link defined between Brand and Product
2. Database synced with link relationship
3. Next: Consume Workflow Hooks (Part 2 of Lesson 2)

The link is now defined at the infrastructure level. Next, we’ll make it functional by consuming the productsCreated workflow hook to automatically link brands to products when products are created.

Ready to continue? Let me know when all checks pass, and we’ll move on to workflow hooks.