Установка Medusa.js: полное руководство для headless commerce
Ручная настройка headless-коммерции часто забирает целый день, и всё равно появляются ошибки в конфигурации Redis. Medusa.js решает эту проблему: одна CLI-команда разворачивает бэкенд, админку и storefront. Мы покажем, как установить и настроить Medusa 2.x правильно, с учётом production-требований.
Что такое Medusa.js и зачем он вам?
Medusa.js — open-source headless commerce платформа на Node.js, альтернатива Shopify и Magento. В отличие от монолитных решений, Medusa даёт полный контроль над API и бэкендом. Вы не привязаны к шаблонам — используете любой фронтенд (Next.js, Nuxt, React). Компании с технической командой выбирают Medusa для кастомизации бизнес-логики без ограничений платформы.
Почему Medusa.js выгоднее Shopify для масштабируемого магазина?
Shopify — быстрый старт, но с ростом бизнеса вы упираетесь в лимиты: высокие комиссии с транзакций, невозможность кастомизировать логику корзины, вендор-лок. Medusa даёт гибкость: вы управляете кодом, не платите комиссию, можете интегрировать любую платёжную систему (Stripe, PayPal, ЮKassa). По тестам, Medusa на собственных серверах обходится в 2-3 раза дешевле при нагрузке от 10 000 заказов в месяц. Экономия на комиссиях может достигать $2 500 в месяц при обороте $100 000.
| Критерий | Shopify | Medusa.js |
|---|---|---|
| Комиссия с транзакций | 2.9% + 30¢ (или меньше) | 0% |
| Кастомизация бэкенда | Ограничена | Полная (Node.js) |
| Вендор-лок | Да (сложно мигрировать) | Нет (открытый код) |
| Хостинг | Только Shopify | Любой (VPS, облако) |
| Производительность (LCP) | Средняя | Высокая (SSR, кэш) |
Как установить Medusa.js за 5 минут?
Medusa 2.x требует Node.js 20+, PostgreSQL 15+ и Redis 7+. Официальный CLI create-medusa-app разворачивает бэкенд и опционально Next.js Storefront и Admin Dashboard одной командой. Согласно официальной документации Medusa, установка через CLI занимает менее 5 минут.
Быстрый старт
# Установка через официальный CLI npx create-medusa-app@latest mystore Интерактивный setup спросит имя проекта, нужен ли Next.js Storefront, нужен ли Admin Dashboard, строку подключения к PostgreSQL. Если вы впервые работаете с Medusa — выбирайте всё, получите готовую песочницу.
Ручная установка и конфигурация
mkdir mystore && cd mystore npm init -y npm install @medusajs/medusa @medusajs/framework # Инициализация структуры npx medusa new . --skip-db # Переменные окружения cat > .env << 'EOF' DATABASE_URL=postgresql://medusa:password@localhost:5432/medusa_db REDIS_URL=redis://localhost:6379 JWT_SECRET=$(openssl rand -base64 32) COOKIE_SECRET=$(openssl rand -base64 32) STORE_CORS=http://localhost:8000 ADMIN_CORS=http://localhost:9000 AUTH_CORS=http://localhost:9000,http://localhost:8000 EOF # Применение миграций и seed начальных данных npx medusa db:create npx medusa db:migrate npx medusa user -e [email protected] -p AdminPass123 --invite # Запуск dev-сервера npx medusa dev Настройка Admin Dashboard
# Admin — отдельный Vite-проект npm create @medusajs/admin-vite-plugin@latest medusa-admin cd medusa-admin npm install npm run dev # http://localhost:9000 Как настроить Medusa для высокой нагрузки без потери производительности?
Однажды мы настраивали Medusa для интернет-магазина с 50 000 товаров и 20 000 заказов в месяц. Начали с базовой установки, но столкнулись с проблемой производительности из-за N+1 запросов при загрузке категорий. Оптимизация через Redis-кэширование и настройка асинхронной обработки очередей для обновления товаров позволили снизить TTFB с 2 секунд до 300 мс. Ключевые шаги включают настройку пула подключений к PostgreSQL (например, 20 соединений), включение кэширования запросов через Redis, и использование batch-обработки для массовых операций.
Типичные ошибки и их решения
- Ошибка подключения к Redis: проверьте, что Redis запущен и порт указан верно. Medusa без Redis не работает.
- Hydration mismatch в Storefront: если используете Next.js, убедитесь, что серверный и клиентский рендеринг согласованы.
- CORS-ошибки: в .env правильно укажите STORE_CORS, ADMIN_CORS, AUTH_CORS — иначе фронтенд не достучится до API. | Переменная | Описание | |------------|----------| | DATABASE_URL | Строка подключения к PostgreSQL | | REDIS_URL | Строка подключения к Redis | | JWT_SECRET | Секрет для подписи JWT | | COOKIE_SECRET | Секрет для подписи кук | | STORE_CORS | Разрешённые источники для storefront | | ADMIN_CORS | Разрешённые источники для admin | | AUTH_CORS | Разрешённые источники для auth |
Что входит в работу по настройке?
Мы не просто ставим пакеты — мы готовим production-решение:
- Развёртывание бэкенда на выделенном сервере или в Docker-контейнерах.
- Интеграция с вашей базой данных (миграции, seed, бэкапы).
- Настройка Redis для кэширования и очередей.
- Деплой админ-панели и storefront (Next.js, Nuxt).
- Настройка CORS, SSL, CI/CD.
- Передача полной документации и доступов.
- Обучение команды работе с админкой.
Процесс работы
- Аналитика — обсуждаем требования, нагрузку, выбираем стек (Next.js vs Nuxt, база данных).
- Проектирование — архитектура: бэкенд, микросервисы, Redis.
- Реализация — установка, конфигурация, кастомизация модулей.
- Тестирование — нагрузочное тестирование, проверка Core Web Vitals.
- Деплой — развёртывание на production, настройка мониторинга.
- Поддержка — гарантия 30 дней на выявление скрытых ошибок, SLA 4 часа.
Сроки и гарантии
Базовая установка + настройка окружения + первый запуск — от 2 до 4 часов. Полный production-деплой с Docker, SSL и CI/CD — до 1 дня. Сроки зависят от сложности кастомизаций. Наш опыт — более 30 проектов на Node.js, мы предоставляем гарантию 30 дней на бесперебойную работу после деплоя. Каждый проект проходит аудит безопасности и нагрузочное тестирование.
Если вам нужен production-деплой Medusa.js, свяжитесь с нами для оценки проекта. Получите консультацию прямо сейчас.