Custom Modules

src/modules/blog/
├── models/
│   └── post.ts          # Data model definitions
├── service.ts           # Main service class
└── index.ts             # Module definition export

// src/modules/blog/models/post.ts
import { model } from "@medusajs/framework/utils"

const Post = model.define("post", {
  id: model.id().primaryKey(),
  title: model.text(),
  content: model.text().nullable(),
  published: model.boolean().default(false),
})

// note models automatically get created_at, updated_at and deleted_at added - don't add these explicitly

export default Post

// src/modules/blog/service.ts
import { MedusaService } from "@medusajs/framework/utils"
import Post from "./models/post"

class BlogModuleService extends MedusaService({
  Post,
}) {}

export default BlogModuleService

// src/modules/blog/index.ts
import BlogModuleService from "./service"
import { Module } from "@medusajs/framework/utils"

export const BLOG_MODULE = "blog"

export default Module(BLOG_MODULE, {
  service: BlogModuleService,
})

// ❌ WRONG - dashes will break the module
export const PRODUCT_REVIEW_MODULE = "product-review" // Don't do this!
export default Module("product-review", { service: ProductReviewService })

// ✅ CORRECT - use camelCase
export const PRODUCT_REVIEW_MODULE = "productReview"
export default Module("productReview", { service: ProductReviewService })

// medusa-config.ts
module.exports = defineConfig({
  // ...
  modules: [{ resolve: "./src/modules/blog" }],
})

# Step 5: Generate migrations (creates migration files)
# Command format: npx medusa db:generate <module-name>
npx medusa db:generate blog

# Step 6: Run migrations (applies changes to database)
# This command takes NO arguments
npx medusa db:migrate

// In API routes
const blogService = req.scope.resolve("blog")
const post = await blogService.createPosts({ title: "Hello World" })

// In workflow steps
const blogService = container.resolve("blog")
const posts = await blogService.listPosts({ published: true })

// Create - pass object or array of objects
const post = await blogService.createPosts({ title: "Hello" })
const posts = await blogService.createPosts([
  { title: "One" },
  { title: "Two" },
])

// Retrieve - by ID, with optional select/relations
const post = await blogService.retrievePost("post_123")
const post = await blogService.retrievePost("post_123", {
  select: ["id", "title"],
})

// List - with filters and options
const posts = await blogService.listPosts()
const posts = await blogService.listPosts({ published: true })
const posts = await blogService.listPosts(
  { published: true }, // filters
  { take: 20, skip: 0, order: { created_at: "DESC" } } // options
)

// List with count - returns [records, totalCount]
const [posts, count] = await blogService.listAndCountPosts({ published: true })

// Update - by ID or with selector/data pattern
const post = await blogService.updatePosts({ id: "post_123", title: "Updated" })
const posts = await blogService.updatePosts({
  selector: { published: false },
  data: { published: true },
})

// Delete - by ID, array of IDs, or filter object
await blogService.deletePosts("post_123")
await blogService.deletePosts(["post_123", "post_456"])
await blogService.deletePosts({ published: false })

// Soft delete / restore
await blogService.softDeletePosts("post_123")
await blogService.restorePosts("post_123")

// src/modules/blog/loaders/hello-world.ts
import { LoaderOptions } from "@medusajs/framework/types"

export default async function helloWorldLoader({ container }: LoaderOptions) {
  const logger = container.resolve("logger")
  logger.info("[BLOG MODULE] Started!")
}

// Export in module definition (src/modules/blog/index.ts)
import helloWorldLoader from "./loaders/hello-world"

export default Module("blog", {
  service: BlogModuleService,
  loaders: [helloWorldLoader],
})