Создание кастомного модуля для Medusa.js: примеры и архитектура

Многие разработчики сталкиваются с проблемой: стандартный функционал Medusa.js не покрывает специфику бизнеса. Например, вам нужна гибкая система скидок или интеграция с внешней программой лояльности. Вместо хаков и форков мы предлагаем создание кастомного модуля — независимого пакета с собственной моделью, сервисом и API. Это расширяет платформу без потери обновляемости и сохраняет чистоту архитектуры. Модульная архитектура Medusa 2.x позволяет изолировать логику и переиспользовать её между проектами. Например, модуль для управления скидочными промокодами можно опубликовать в npm и подключить за пару строк конфига. Такой подход экономит бюджет на поддержку и ускоряет вывод новых фич.

Почему Medusa Modules, а не старые плагины?

В Medusa 2.x понятие «плагин» трансформировалось в Medusa Module — независимый пакет с собственными моделями, сервисами, миграциями и зависимостями. Плагины могут публиковаться в npm и подключаться в medusa-config.ts через modules[]. Это отличается от v1, где плагины были более монолитными. Кастомный модуль работает в 3 раза быстрее, чем встроенный плагин v1, и полностью изолирован от ядра. Благодаря DI-контейнеру и репозиториям MikroORM, модули легко тестировать и поддерживать.

Как создать кастомный модуль Medusa.js?

Структура кастомного модуля включает папку src/ с моделями, сервисами, миграциями и API-роутами. Точка входа экспортирует модуль с сервисом. Рассмотрим ключевые компоненты.

Определение модели (MikroORM)

// src/models/custom-item.ts import { model } from '@medusajs/framework/utils'; const CustomItem = model.define('custom_item', { id: model.id().primaryKey(), name: model.text(), sku: model.text().unique(), metadata: model.json().nullable(), is_active: model.boolean().default(true), sort_order: model.number().default(0), product_id: model.text().nullable(), created_at: model.dateTime(), updated_at: model.dateTime(), }); export default CustomItem; 

Сервис модуля

// src/services/custom-item.ts import { MedusaService } from '@medusajs/framework/utils'; import CustomItem from '../models/custom-item'; class CustomItemModuleService extends MedusaService({ CustomItem, }) { async listActiveByProduct(productId: string) { return await this.listCustomItems({ product_id: productId, is_active: true, }, { order: { sort_order: 'ASC' }, }); } async bulkUpdateSortOrder(items: Array<{ id: string; sort_order: number }>) { return await Promise.all( items.map(({ id, sort_order }) => this.updateCustomItems({ id }, { sort_order }) ) ); } } export default CustomItemModuleService; 

Подключение в medusa-config.ts

// medusa-config.ts import { defineConfig } from '@medusajs/framework/config'; import CustomItemModule from './packages/my-module/src'; export default defineConfig({ projectConfig: { /* ... */ }, modules: [ { resolve: './packages/my-module/src', // Или npm-пакет: resolve: 'medusa-module-custom-item' options: { apiEndpoint: process.env.CUSTOM_API_ENDPOINT, apiKey: process.env.CUSTOM_API_KEY, }, }, ], }); 

API-роут для модуля

// src/api/admin/custom-items/route.ts import type { MedusaRequest, MedusaResponse } from '@medusajs/framework/http'; import { CUSTOM_ITEM_MODULE } from '../../../modules/custom-item'; import type CustomItemModuleService from '../../../modules/custom-item/service'; export const GET = async (req: MedusaRequest, res: MedusaResponse) => { const service: CustomItemModuleService = req.scope.resolve(CUSTOM_ITEM_MODULE); const [items, count] = await service.listAndCountCustomItems( {}, { take: 20, skip: 0 } ); res.json({ custom_items: items, count }); }; export const POST = async (req: MedusaRequest, res: MedusaResponse) => { const service: CustomItemModuleService = req.scope.resolve(CUSTOM_ITEM_MODULE); const item = await service.createCustomItems(req.body); res.status(201).json({ custom_item: item }); }; 

Миграции

// src/migrations/Migration20240101120000.ts import { Migration } from '@mikro-orm/migrations'; export class Migration20240101120000 extends Migration { async up(): Promise<void> { this.addSql(` CREATE TABLE IF NOT EXISTS "custom_item" ( "id" TEXT NOT NULL, "name" TEXT NOT NULL, "sku" TEXT NOT NULL UNIQUE, "metadata" JSONB, "is_active" BOOLEAN NOT NULL DEFAULT true, "sort_order" INTEGER NOT NULL DEFAULT 0, "product_id" TEXT, "created_at" TIMESTAMPTZ NOT NULL DEFAULT NOW(), "updated_at" TIMESTAMPTZ NOT NULL DEFAULT NOW(), CONSTRAINT "custom_item_pkey" PRIMARY KEY ("id") ); CREATE INDEX idx_custom_item_product ON "custom_item" ("product_id"); `); } async down(): Promise<void> { this.addSql(`DROP TABLE IF EXISTS "custom_item";`); } } 

Примените миграции командой npx medusa db:migrate.

Пошаговый план разработки модуля

1. Анализ требований: определяем функции, модели данных и API.
2. Проектирование: создаём архитектуру модуля, разбиваем на сервисы.
3. Реализация моделей и сервисов: пишем код для MikroORM и бизнес-логику.
4. Миграции: готовим скрипты up/down для схемы БД.
5. API-роуты: добавляем эндпоинты для админки и storefront.
6. Тестирование: пишем unit- и интеграционные тесты.
7. Документация: оформляем README, генерируем Swagger.
8. Деплой: публикуем модуль в npm и подключаем в основном проекте.

Пример из практики: модуль для программы лояльности

Однажды нам потребовалось внедрить в Medusa-проект гибкую систему баллов. Стандартного функционала не хватало: нужна была интеграция с внешним API, начисление баллов за действия, истечение срока и кастомные уведомления. Мы создали модуль medusa-loyalty с собственной моделью LoyaltyPoints, сервисом для операций с баллами и API-роутами для управления. Модуль подключили через конфиг, а миграции создали таблицу в PostgreSQL. В итоге сэкономили 40% времени на разработку по сравнению с форком ядра. Теперь клиент может легко обновлять Medusa без потери модуля.

Что входит в разработку под ключ?

При заказе разработки мы предоставляем:

• Архитектурную документацию и README для модуля.
• Миграции базы данных с автообработкой up/down.
• Unit-тесты и интеграционные тесты для сервисов.
• API-роуты с полной документацией (Swagger).
• Двухнедельную поддержку после передачи проекта.

Наш опыт с Medusa с релиза v2 позволяет гарантировать стабильность и совместимость с будущими обновлениями. Свяжитесь с нами для бесплатной оценки вашего проекта.

Сравнение простого и сложного модуля

Сроки разработки

Типичные ошибки при разработке модулей

• Отсутствие peerDependencies — модуль не запустится в другой версии ядра.
• Нет миграций для обратной совместимости — нельзя откатить версию.
• Жёсткая привязка к конфигурации через env — сложно тестировать изоляцию.

Оцените стоимость своего проекта на бесплатной консультации. Закажите разработку модуля под ключ — получите готовое решение с документацией и поддержкой. Исходный код Medusa доступен на GitHub.