Встановлення 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. Medusa.js кращий за Shopify в 2-3 рази за вартістю утримання при високому навантаженні.
Порівняння Shopify та Medusa.js
| Критерій | 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.
- Передача повної документації та доступів.
- Навчання команди роботі з адмінкою.
Вартість налаштування Medusa.js фахівцем починається від $500.
Процес роботи
- Аналітика — обговорюємо вимоги, навантаження, обираємо стек (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, зв'яжіться з нами для оцінки проекту. Отримайте консультацію прямо зараз.