Сегодня мы хотим препарировать популярное open-source решение для e-commerce - Medusa.js. В рекламных проспектах все выглядит гладко: headless-архитектура, модульность, богатый функционал «из коробки». Но что скрывается за красивым фасадом, когда дело доходит до реальной разработки и кастомизации?
Мы изучили внутреннюю документацию по работе с Medusa и готовы поделиться выводами. Эта статья — попытка дать трезвую оценку фреймворку, чтобы вы могли решить, подходит ли он для вашего следующего проекта или лучше обойти его стороной.
Что Medusa предлагает «из коробки»?
На первый взгляд, функционал действительно впечатляет. Medusa предоставляет множество готовых инструментов, которые экономят уйму времени на старте.
Админ-панель позволяет управлять практически всеми аспектами магазина:
Настройки магазина (Store): Управление валютами, регионами, налогами и складами. Провайдеры оплаты привязываются к конкретному региону.
Каналы продаж (Sales Channels): Medusa позволяет в рамках одного сервиса создать несколько витрин (фронт-магазинов), каждая со своим набором товаров, складов и настроек.
Управление каталогом: Есть иерархия категорий с поддержкой вложенности, коллекции для подборок («Лучшие предложения») и управление тегами товаров.
Товары и остатки (Inventory): Можно добавлять варианты товаров (например, по цвету или размеру), и у каждого варианта будет своя складская позиция.
Клиенты и прайс-листы: Поддерживается управление пользователями и их группами. Для разных групп можно настроить индивидуальные цены через прайс-листы.
Маркетинг: Есть гибкая настройка скидок и акций с разными типами и ограничением по сроку действия.
Заказы: Стандартный набор функций — просмотр заказов, отгрузка товаров и ручной прием оплаты.
Доставка: Изначально доступна только ручная настройка, но есть возможность подключать внешних провайдеров.
Этот набор позволяет быстро запустить небольшой интернет-магазин с минимальными усилиями, используя готовые блоки: каталог, корзину, оформление заказа, оплату и доставку.
Заглянем под капот: Архитектура для технарей
Для разработчика Medusa предлагает довольно стройную архитектуру, построенную на нескольких ключевых концепциях.
Воркфлоу (Workflows): Это аналоги use-кейсов, которые выполняют определенное действие (создание, обновление, удаление). Процесс выполняется пошагово, и каждый шаг работает как транзакция в базе данных: если что-то пошло не так, действие откатывается.
Событийная модель (Events): Почти каждый воркфлоу генерирует события, например product.created. Сама система мало что обрабатывает, но это открывает простор для кастомной логики. Например, на событие восстановления пароля можно повесить обработчик для отправки письма. Все события работают через очередь в Redis по принципу FIFO.
Модульность: Фреймворк состоит из отдельных модулей, реализующих конкретную фичу (например, товары). Внутри модуля содержатся модели, сервисы, API-роуты, воркфлоу и даже собственные cron-задачи. Подключаются они через главный конфигурационный файл
medusa-config.Миграции: Medusa имеет встроенную систему генерации миграций для модулей. Она может создать либо полный SQL-файл, либо только дифф с изменениями.
Кэширование: «Из коробки» поддерживается Redis и кэш в памяти.
Файловое хранилище: Легко интегрируется с любым S3-совместимым хранилищем через подключение соответствующего модуля.
Когда стоит использовать Medusa? (А когда бежать без оглядки)
Несмотря на все плюсы, Medusa — это НЕ универсальный инструмент для любого интернет-магазина. Попытка построить на ней условный «Wildberries за копейки» обречена на провал — переделка займет больше времени, чем разработка с нуля.
✅ Идеальные сценарии:
Заказчик полностью согласен на существующий функционал, и кастомизация ядра не требуется.
Нужен один или несколько простых интернет-магазинов, которые можно разграничить через каналы продаж.
Требуется быстрый запуск стандартного e-commerce проекта с минимальными вложениями. Однако плагинов для сервисов из РФ все еще немного, тогда как для зарубежных сервисов их существенно больше, например Stripe, Paypal, FedEx.
❌ Когда использование не оправдано:
Требуется изменение базовой логики. Кастомизация процессов ядра превращается в полный перенос кода из ядра в свой проект, что может занять значительное время.
Нужна сложная структура магазинов. Например, головная админка и подчиненные партнерские сторы.
Планируется работа с юридическими лицами. Система не предполагает смены роли покупателя, а доработки снова потребуют переноса и адаптации кода из ядра.
Проект рассчитан на большую нагрузку. Medusa довольно плохо оптимизирована для высоких нагрузок.
Проблемы и боль: С чем придется столкнуться
На бумаге все выглядит неплохо, но на практике разработка на Medusa сопряжена с рядом серьезных проблем.
Кастомизация — это иллюзия. Радикально изменить логику, модели или ответы API, которые находятся в ядре, нельзя. Хотите добавить поле в модель или свою валидацию? Делайте через свой модуль. Но многие внутренние инструменты, типы и воркфлоу, которые есть в ядре, просто недоступны извне. Приходится изобретать велосипеды, даже если в ядре уже есть готовое решение, но оно не экспортируется.
Баги. Их много, и большинство из них мелкие. Но разработчики часто не считают их багами, а ишьюсы на GitHub могут висеть годами, игнорироваться или просто закрываться. Например, баг с обновлением поля
updatedAt висел почти два года.Слабое комьюнити. Практически нет ничего, кроме официальной документации. Сама документация хоть и обширная, но очень поверхностная — многие вещи приходится изучать «методом тыка».
Ограничения API. «Из коробки» нет возможности фильтровать данные по вложенным полям из других таблиц (модулей). Например, нельзя отфильтровать товары по атрибутам, если атрибуты реализованы в отдельном модуле.
Кастомизация админки. Новый функционал можно добавлять только виджетами — отдельными блоками на существующих страницах. Изменить сами страницы, отключить лишние функции или поменять запросы нельзя.
Высокий порог входа. Новому разработчику, не знакомому с Medusa, будет очень сложно влиться в проект. Доработки требуют глубокого понимания архитектуры и умения копаться в исходниках ядра.
Выводы
Medusa.js — мощный, но очень нишевый инструмент. Это отличный выбор, если вам нужен стандартный магазин и вы готовы работать в рамках, заданных фреймворком. В этом случае вы действительно сможете запуститься очень быстро.
Однако если ваш проект предполагает кастомизацию бизнес-логики, сложные интеграции или нестандартные сущности, Medusa может превратиться из помощника в настоящую Горгону, которая будет тормозить разработку на каждом шагу. Негибкость ядра, проблемы с кастомизацией и слабая поддержка сообщества делают ее рискованным выбором для сложных и долгосрочных проектов.
Бонус-кейс: Mercur.js — превращаем Medusa в маркетплейс
Если Medusa — это фундамент для одного магазина, то
Mercur.js — это open-source надстройка, которая превращает его в полноценный маркетплейс. По сути, это большой модуль, добавляющий логику взаимодействия с продавцами (селлерами) и улучшающий некоторые базовые функции Medusa.
Что нового под капотом?
Mercur добавляет два больших блока функциональности: расширенную админ-панель для владельца площадки и отдельный личный кабинет для каждого продавца.
В главной Admin-панели появляется:
Управление селлерами: Можно приглашать продавцов на площадку и блокировать их.
Управление комиссиями: Гибкая настройка комиссий — глобально для всей площадки, для отдельных категорий, конкретных селлеров или их комбинаций.
Система запросов (Requests): Селлеры могут отправлять на модерацию запросы на добавление новых товаров, категорий, тегов, а также на удаление отзывов.
Правила площадки: Владелец может настроить правила, например, разрешить селлерам только добавлять свои остатки к уже существующим товарам или включить обязательную премодерацию всех новых товаров.
Для продавцов (Vendor Panel) реализован отдельный дашборд:
Это отдельное веб-приложение, где каждый селлер видит только свои данные.
Онбординг: Процесс для новых продавцов, после которого открывается доступ к статистике магазина.
Управление магазином: У селлера есть урезанный аналог админки Medusa для управления своими заказами, товарами, остатками и покупателями.
Отзывы: Можно управлять отзывами на свои товары и на свой магазин, отвечать на них или запрашивать удаление через главную админку.
Уведомления: Встроенная система уведомлений о новых заказах, результатах модерации и других событиях.
Проблемы и суровая реальность
Несмотря на мощный функционал, Mercur — это очень сырой продукт, который «из коробки» практически не работает.
Зависимость от западных сервисов: Весь ключевой функционал завязан на платные сервисы, недоступные в РФ: Stripe для выплат селлерам, Algolia для поиска, TalkJS для чатов, Resend для email-рассылок. Их замена потребует непредсказуемого количества времени на доработку.
Все нужно допиливать: Приглашения селлеров не работают без настройки email-провайдера. Поиск не работает без ключей Algolia. Чат не работает без настройки TalkJS.
Отставание от Medusa: Mercur сильно зависит от обновлений ядра Medusa и на момент анализа уже значительно отставал по версиям.
Отсутствие документации: Если у Medusa есть хотя бы какая-то документация, то у Mercur гайдов нет «от слова совсем».
Нет ролевой модели: Внутри кабинета селлера нет разделения ролей — все приглашенные пользователи имеют одинаковый доступ.
Вердикт по Mercur.js
Mercur — это скорее заготовка или proof-of-concept, чем готовое решение.
Когда может подойти? Для зарубежного проекта, где есть доступ к Stripe и Algolia, и нужна быстрая база для маркетплейса. Главный плюс — он распространяется как исходный код, а значит, его можно модифицировать как угодно.
Когда не стоит? Если вы работаете на российском рынке или не готовы вкладывать серьезные ресурсы в доработку и замену ключевых сервисов. Для простого интернет-магазина он избыточен и не дает преимуществ перед обычной Medusa.