Medusa v2 Custom Modules

Before writing code

Fetch live docs:

1. Fetch https://docs.medusajs.com/learn/fundamentals/modules for module overview
2. Web-search site:docs.medusajs.com DML data model reference for model property types
3. Web-search site:docs.medusajs.com MedusaService methods for base service API
4. Web-search site:docs.medusajs.com module links for linking modules together
5. Web-search site:docs.medusajs.com module container registration for dependency injection

Module Concept

A module is a self-contained package of functionality in Medusa v2:

• Encapsulates data models, services, and business logic
• Registered in medusa-config.ts under the modules array
• Accessed from workflows, API routes, and subscribers via the dependency container
• Modules communicate through links, not direct imports

Module Directory Structure

DML Data Models

Property Types

Relationship Types

Model Definition Skeleton

// src/modules/my-module/models/my-entity.ts
// Fetch live docs for current DML model API
import { model } from "@medusajs/framework/utils"

const MyEntity = model.define("my_entity", {
  id: model.id(), name: model.text(),
  // Fetch live docs for property options and relationships
})

Service Pattern

Every module exposes a service that extends MedusaService:

// src/modules/my-module/service.ts
// Fetch live docs for MedusaService generic signature
import { MedusaService } from "@medusajs/framework/utils"
import MyEntity from "./models/my-entity"

class MyModuleService extends MedusaService({ MyEntity }) {}
export default MyModuleService // Add custom methods as needed

Inherited MedusaService Methods

The method names are auto-generated from the model name (e.g., createMyEntity, listMyEntities).

Module Definition Export

// src/modules/my-module/index.ts
// Fetch live docs for Module definition shape
import { Module } from "@medusajs/framework/utils"
import MyModuleService from "./service"

export const MY_MODULE = Module("my-module", {
  service: MyModuleService,
})

Registration in medusa-config.ts

// Inside modules array
// Fetch live docs for module registration options
{ resolve: "./src/modules/my-module" }

Module Links

Links connect data models across different modules without coupling:

Link Definition Skeleton

// src/links/product-my-entity.ts
// Fetch live docs for defineLink API
import { defineLink } from "@medusajs/framework/utils"
import ProductModule from "@medusajs/medusa/product"
import { MY_MODULE } from "../modules/my-module"

Links are queried using the query utility from the Medusa container, not through direct service calls.

Loaders

Loaders run when the module initializes (server startup):

• Seed default data
• Register event listeners
• Validate configuration
• Set up external connections

Container Resolution

Modules register their service in the dependency injection container:

• Resolved by module key: container.resolve("my-module")
• Available in workflows, API routes, subscribers, and other services
• Never import a module's service directly -- always resolve from the container

Best Practices

• One module per bounded context -- keep modules focused and cohesive
• Use DML models exclusively -- never write raw SQL or use Mikro-ORM directly
• Extend MedusaService for CRUD -- only add custom methods for non-standard logic
• Use module links to connect to core entities -- never modify core module tables
• Run npx medusa db:generate after every model change to create migrations
• Export a constant for your module key (e.g., MY_MODULE) and reuse it everywhere

Common Patterns

Fetch the Medusa module documentation for exact DML property options, MedusaService generics, and link definition patterns before implementing.