orcaqubits/medusa-modules

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

| File | Purpose | |------|---------| | src/modules/my-module/models/my-entity.ts | DML data model | | src/modules/my-module/service.ts | Service extending MedusaService | | src/modules/my-module/loaders/seed.ts | Optional loader (runs on startup) | | src/modules/my-module/migrations/ | Auto-generated by CLI | | src/modules/my-module/index.ts | Module definition export |

DML Data Models

Property Types

| DML Type | Database Column | Notes | |----------|----------------|-------| | model.id() | Primary key UUID | Auto-generated | | model.text() | text / varchar | String fields | | model.number() | integer | Numeric fields | | model.bigNumber() | numeric | Precise decimals (prices) | | model.boolean() | boolean | True/false | | model.dateTime() | timestamptz | Date/time values | | model.json() | jsonb | Arbitrary JSON | | model.enum() | enum | Constrained values | | model.array() | array | Array of primitives |

Relationship Types

| Relationship | DML Method | Description | |-------------|-----------|-------------| | Has One | model.hasOne() | One-to-one owned | | Has Many | model.hasMany() | One-to-many owned | | Belongs To | model.belongsTo() | Inverse of hasOne/hasMany | | Many to Many | model.manyToMany() | Junction table auto-created |

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

| Method Pattern | Purpose | |---------------|---------| | create<Entity>(data) | Create one or many records | | update<Entity>(data) | Update records by selector or ID | | delete<Entity>(ids) | Soft-delete records | | retrieve<Entity>(id, config) | Retrieve single record by ID | | list<Entity>(filters, config) | List with filters, pagination, relations | | softRestore<Entity>(ids) | Restore soft-deleted records |

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 Type | Purpose | |-----------|---------| | One-to-one link | Connect a custom entity to a core entity (e.g., product) | | One-to-many link | One core entity linked to many custom entities | | List link | Bidirectional many-to-many between modules |

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

| Pattern | When to Use | |---------|------------| | Custom module + link to Product | Adding metadata/features to products | | Custom module + link to Order | Order-related extensions (loyalty, tracking) | | Standalone module | Independent domain (CMS, analytics, reviews) | | Module with loader | Pre-seeding data or external service setup |

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