Lesson 2 Extend Medusa

By the end of this lesson, you will:

• Link brands to products using Module Links
• Extend core workflows using Workflow Hooks
• Configure additional_data for custom parameters
• Query linked records across modules using Query

Time: 45-60 minutes

Prerequisites: Completed Lesson 1 (Brand Module, createBrandWorkflow, POST /admin/brands)

What We’re Building

In Lesson 1, you created a brands system. Now we’ll integrate it with Medusa’s core Product Module:

New capabilities:

• Associate a brand with a product when creating it
• Retrieve a product with its brand details
• List all brands with their associated products
• Maintain module isolation (no direct dependencies!)

By the end, you’ll be able to:

Architecture Overview: Extending Without Breaking

The Challenge

You want to add brands to products. In other platforms, you might:

Problems:

• Core modules shouldn’t know about custom modules
• Breaks when Medusa updates
• Can’t reuse Brand Module elsewhere
• Violates single responsibility

The Medusa Solution

Medusa provides three tools to extend core features safely:

1. Module Links: Connect data models across modules while maintaining isolation
2. Workflow Hooks: Inject custom logic into core workflows
3. Additional Data: Pass custom parameters through core API routes

Documentation: Module Links (opens in a new tab) | Workflow Hooks (opens in a new tab) | Additional Data (opens in a new tab)

Part 1: Define Module Link

What is a Module Link?

A Module Link creates a relationship between data models of different modules while maintaining module isolation.

Key properties:

• Neither module imports from the other
• Link is managed separately in src/links/
• Both modules remain reusable
• Relationship is defined declaratively

Think of it like a junction table:

• In SQL: A product_brand table with product_id and brand_id columns
• In Medusa: A link definition that creates this automatically

Documentation: Module Links Guide (opens in a new tab)

Step 2.1: Define the Link

Create src/links/product-brand.ts:

Let’s break this down:

1. Import Module Definitions:

• Custom modules: Import from ../modules/[name]
• Core modules: Import from @medusajs/medusa/[module-name]

2. Access Linkable Property:

• Every module exports a linkable property
• Contains link configurations for each data model
• Property name is snake-case model name

3. Define the Link:

Parameters:

• First: Product (with isList: true - many products per brand)
• Second: Brand

The isList property:

Order matters! The link configuration order affects how you create links later.

Step 2.2: Sync Link to Database

Module links are stored in a database table. Run:

This:

• Creates a link_product_brand table (or similar)
• Stores relationships between product IDs and brand IDs
• Enables querying across modules

Checkpoint 2.1: Verify Module Link

Verification Questions

1. Why use Module Links instead of adding brand_id to Product model?

2. What does isList: true mean?

3. What happens if you forget to run migrations?

Implementation Check

1. Check migrations succeeded:

   bashCopy

   npx medusa db:migrate

   Expected: Migration runs successfully

2. Check build succeeds:

   bashCopy

   npm run build

3. Show me your file:

   • src/links/product-brand.ts

Common Issues

“Link not found”

• Check file is in src/links/ directory
• Ensure proper import paths

“Migration failed”

• Check database is running
• Review migration output for errors

Testing Checklist

• Not done: Link file created in src/links/
• Not done: Migrations ran successfully
• Not done: Build succeeds

Part 2: Extend Create Product Workflow

What are Workflow Hooks?

Workflow Hooks are predefined points in core workflows where you can inject custom logic.

Example: Medusa’s createProductsWorkflow has hooks:

• productsCreated - Runs after products are created
• productsUpdated - Runs after products are updated
• productsDeleted - Runs after products are deleted

You can “consume” (listen to) these hooks and perform custom actions.

Why hooks?

• Extend core workflows without modifying them
• Keep customizations separate and maintainable
• Workflows remain upgradeable

Documentation: Workflow Hooks Guide (opens in a new tab)

Step 2.2: Consume productsCreated Hook

When a product is created, we want to link it to a brand (if brand_id was provided).

Create src/workflows/hooks/created-product.ts:

Let’s break this down:

1. Hook Consumption:

• First parameter: Hook step function
• Second parameter: Compensation function (for rollback)

2. Hook Input:

• products: Array of created products (from workflow)
• additional_data: Custom data from API request body

3. Verify Brand Exists:

• Throws error if brand doesn’t exist
• Prevents linking to non-existent brands

4. Create Links:

Link object structure:

• Keys: Module names (in the order defined in defineLink)
• Values: Objects with {model}_id properties

Order matters! Must match the order in defineLink:

5. Compensation Function:

• Removes links if an error occurs later
• Maintains data consistency

Documentation: Hook Consumption (opens in a new tab) | Link Creation (opens in a new tab)

Step 2.3: Configure additional_data

To pass brand_id through the create product API route, configure additional_data validation.

Update or create src/api/middlewares.ts:

What’s happening?

additionalDataValidator:

• Configures validation for additional_data request body parameter
• Uses Zod schemas for each property
• Properties are passed to workflow hooks

Why optional?

• Not all products need a brand
• Allows creating products without brands

Documentation: Additional Data Validation (opens in a new tab)

Checkpoint 2.2: Test Creating Product with Brand

Verification Questions

1. Why verify the brand exists before creating the link?

2. What happens if you don’t add a compensation function to the hook?

3. Why is brand_id optional in additionalDataValidator?

Implementation Check

1. Build succeeds:

   bashCopy

   npm run build

2. Show me your files:

   • src/workflows/hooks/created-product.ts
   • src/api/middlewares.ts

Test Creating Product with Brand

Step 1: Create a brand (if you haven’t already):

Save the brand ID from the response.

Step 2: Get a shipping profile ID (required for products):

Step 3: Create product with brand:

Note on prices: If you’re adding prices to your product variants, remember that Medusa stores prices as-is (not in cents). For example, a $19.99 product should have "amount": 19.99, not 1999.

Expected: Product created successfully

Check logs: You should see “Linked brand to products” or similar

Common Issues

“Brand not found”

• Brand ID is wrong or brand doesn’t exist
• Create brand first

“Hook not running”

• Check file is in src/workflows/hooks/
• Restart dev server
• Check for TypeScript errors

“Invalid additional_data”

• Check additionalDataValidator is configured correctly
• Ensure brand_id is a string

Testing Checklist

• Not done: Product created with brand_id in additional_data
• Not done: No errors in server logs
• Not done: Product creation succeeds

Part 3: Query Linked Records

Querying with fields Parameter

Medusa’s core API routes accept a fields query parameter to retrieve linked data.

Get product with brand:

Response:

The +brand.* syntax:

• + = Add to default fields (don’t replace)
• brand = Linked model name (singular)
• .* = All properties of brand

Documentation: Fields Parameter Guide (opens in a new tab)

Querying with Query.graph()

For custom API routes, use Query to retrieve linked records.

Example: Create an endpoint to get brands with their products.

Update src/api/admin/brands/route.ts:

What’s happening?

1. Resolve Query:

• Query is a Medusa framework tool for cross-module queries
• Registered in the container

2. Query Linked Data:

Parameters:

• entity: Data model name (as defined in model.define)
• fields: Array of properties and relations to retrieve
  • "*" = All properties of brand
  • "products.*" = All properties of linked products (plural!)

Why “products” (plural)? Because brands are linked to a list of products (isList: true in the link definition).

Documentation: Query Guide (opens in a new tab)

Checkpoint 2.3: Test Querying

Verification Questions

1. Why use products.* (plural) instead of product.* (singular)?

2. What’s the difference between fields parameter and Query.graph()?

Implementation Check

1. Build succeeds:

   bashCopy

   npm run build

2. Show me your file:

   • src/api/admin/brands/route.ts

Test Querying

Test 1: Get product with brand:

Expected: Product with brand property

Test 2: Get brands with products:

Expected Response:

Common Issues

“Cannot query products”

• Check link is defined correctly
• Ensure migrations ran
• Verify products are actually linked to brand

“Brand property missing on product”

• Forgot ?fields=+brand.* in query
• Link not created when product was created

Testing Checklist

• Not done: Product retrieved with brand details
• Not done: Brands retrieved with products
• Not done: Both queries return expected data

Lesson 2 Complete! 🎉

What You Built

Amazing work! You’ve extended Medusa’s core functionality:

• ✅ Module Link: Connected brands to products (maintaining isolation)
• ✅ Workflow Hook: Extended createProductsWorkflow to link brands
• ✅ Additional Data: Configured validation for custom parameters
• ✅ Querying: Retrieved linked data across modules

What You Learned

Module Links:

• Create relationships without breaking module isolation
• Neither module depends on the other
• Links are managed separately

Workflow Hooks:

• Extend core workflows without modifying them
• Inject custom logic at predefined points
• Include rollback logic for data consistency

Additional Data:

• Pass custom parameters through core API routes
• Validate with Zod schemas
• Accessible in workflow hooks

Query:

• Retrieve data across modules
• Use fields parameter in core routes
• Use Query.graph() in custom routes

Architecture Reinforcement

1. Why not just add brand_id column to products table?

Problems with direct column:

• Product Module now knows about brands
• Can’t reuse Brand Module elsewhere
• Breaks when Medusa updates Product Module
• Violates single responsibility

Module Links solve this:

• Product Module: No knowledge of brands
• Brand Module: No knowledge of products
• Link: Separate concern, easy to maintain
• Both modules remain reusable

2. How does additional_data reach the workflow hook?

Flow:

1. Client sends request: { additional_data: { brand_id: "..." } }
2. Middleware validates: additionalDataValidator: { brand_id: z.string() }
3. API route executes workflow
4. Workflow passes to hooks: { products, additional_data }
5. Your hook consumes: if (additional_data?.brand_id) { ... }

3. What happens if brand creation fails after linking?

The compensation function runs:

This ensures no orphaned links exist.

Commit Your Work

Ready for Lesson 3?

In Lesson 3: Customize Admin Dashboard, you’ll learn how to:

• Create widgets to display brand on product detail page
• Build UI routes for managing brands
• Use React Query for data fetching
• Integrate Medusa UI components

You’ll build:

• A widget showing brand name on product pages
• A brands management page with a data table
• Full CRUD operations in the admin dashboard

Documentation: Admin Widgets (opens in a new tab) | Admin UI Routes (opens in a new tab) | Medusa UI Components (opens in a new tab)

When you’re ready, let me know and we’ll start Lesson 3!