Створення кастомного модуля для 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.