---
name: medusa-modules-b1e2ade217bb
description: >
  Build custom Medusa v2 modules — DML data models, services extending
  MedusaService, loaders, module links, and container registration. Use when
  creating custom 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

```typescript
// 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`:

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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.


---
Source attribution: OrcaQubits
Original project: https://github.com/OrcaQubits/agentic-commerce-skills-plugins/blob/30cd25c74c8aa7dc49b3ec4847d463f6104439f6/dist/codex/medusa-commerce/skills/medusa-modules/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2024-2026 OrcaQubits AI (https://orcaqubits-ai.com)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: OrcaQubits
Original project: https://github.com/OrcaQubits/agentic-commerce-skills-plugins/blob/30cd25c74c8aa7dc49b3ec4847d463f6104439f6/dist/codex/medusa-commerce/skills/medusa-modules/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering, Product Management
Roles: Backend Developer, Growth Product Manager, Product Manager
Specialties: Backend
Tools: Medusa
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 798e1cc187a43d1dffbb5ba4103e3703c23617cb9489ef7a14e4536e7c95b32a