Представляем готовый к продакшену Medusa DTC Starter от Gorgo

Мы многократно использовали официальный Medusa DTC Starter в своих проектах и довели его до продакшен-уровня.

Сегодня мы публикуем свою версию стартера. Это два приложения, бэкенд Medusa и витрина магазина на Next.js, собранные вместе и уже настроенные. Код лежит в репозитории, магазин можно посмотреть в демо, установка и настройка описаны в документации, короткое описание есть на странице стартера. Лицензия MIT.

Чего не хватает официальному стартеру

Официальный стартер поднимает работающий магазин, но в нём отсутствует то, что отличает демо от магазина в продакшене. Дальше каждый разработчик доделывает это сам: улучшает страницу оформления заказа, локализует магазин и товары, настраивает транзакционные письма, добавляет ревалидацию кэша и прорабатывает SEO. Мы проделали такую работу с Medusa в нескольких проектах и собрали весь этот опыт в наш стартер, чтобы другим разработчикам не приходилось повторять этот путь.

Что внутри

Всё, что есть в официальном стартере, плюс перечисленное ниже. Каждый пункт уже настроен и работает сразу после установки.

Конверсионный чекаут

Покупатель заполняет контакты и адрес в модальных окнах. Длинных форм нет, в отличие от официального стартера. За основу мы взяли оформление заказа в Яндекс KIT. Команда Яндекса развила чекаут Shopify, который в своё время считался эталоном отрасли, и собрала оформление на одном лаконичном экране.

Автозаполнение адреса

Поле адреса подсказывает варианты по мере ввода. После выбора подсказки индекс, город и регион заполняются сами. Встроен сервис DaData, любой другой подключается через тот же интерфейс, а если адрес не найден, то можно переключиться на ручной ввод. Как подключить свой сервис автозаполнения адресов, описано в документации Настройка автозаполнения адреса.

Полная локализация

36 языков для витрины с поддержкой RTL и 241 страна для регионов продаж. Их заводит seed-скрипт, лишние легко вычищаются из его файлов данных. У каждого региона своя валюта, свой склад и свои способы доставки, поэтому перед запуском оставьте только те регионы, где действительно продаёте. Подробности в документации Настройка начальных данных.

Поиск и фильтры по каталогу

Поиск по товарам работает на Store API и подсвечивает совпадения, а когда каталог вырастет, на его место встаёт отдельный движок, например Meilisearch. Фильтры по опциям товара, сортировка по цене и новизне, категории и подкатегории в боковой панели, на мобильных фильтры открываются панелью снизу. Выбранные фильтры остаются в адресе страницы, поэтому ссылкой на подборку можно поделиться. За основу взят каталог магазина брендовой одежды 12 STOREEZ.

Транзакционные письма

Собственный SMTP-провайдер уведомлений отправляет шаблоны React Email через nodemailer. Письма уходят на события покупателя, заказа, доставки и оплаты, за каждое отвечает свой подписчик.

1welcome.tsx                    # покупатель зарегистрировался
2order-placed.tsx               # заказ оформлен
3payment-captured.tsx           # оплата получена
4order-fulfillment-created.tsx  # по заказу создана отправка
5order-completed.tsx            # заказ завершён
6order-transfer-request.tsx     # запрошена передача заказа
7password-reset.tsx             # сброс пароля
8layout.tsx                     # общая вёрстка письма
9i18n/                          # тексты писем на разных языках

Ревалидация кэша по запросу

Когда в каталоге или переводах что-то меняется, подписчик бэкенда отправляет вебхук на витрину. Витрина сбрасывает кэш только тех страниц, которых изменение касается, вместе с sitemap.xml и llms.txt. Пересобирать сайт целиком не нужно. Смотрите что именно сбрасывается в принимающем API витрины.

SEO и AI-краулеры

Карта сайта содержит все URL каталога на 36 языках, а robots.txt закрывает от краулеров корзину, оформление заказа и личный кабинет. У страниц каталога есть канонический URL и hreflang-альтернативы для каждого языка, заданы изображения Open Graph и Twitter. Эндпоинт llms.txt отдаёт каталог AI-краулерам.

Интеграции настраиваются в Admin

API-ключами платёжных провайдеров и параметрами служб доставки должен управлять администратор магазина в Admin, а не разработчик в коде. Модуль интеграций предоставляет для этого раздел Настройки → Интеграции, а хранение, валидацию и шифрование секретов берёт на себя. В стартере он уже зарегистрирован в medusa-config.ts, остаётся добавить провайдер из каталога интеграций и заполнить настройки.

С чего начать

Проект создаётся через CLI Medusa. Понадобятся Node v20 или новее и PostgreSQL 15 или новее, Redis в разработке не обязателен.

npx create-medusa-app@latest --repo-url https://github.com/gorgojs/medusa-dtc-starter

Флаг --repo-url создаёт проект из этого репозитория, а не из официального стартера. Команда сразу применяет миграции, создаёт администратора и наполняет базу начальными данными.

Или можно склонировать репозиторий стартера и настроить бэкенд и витрину по отдельности. Оба способа и разбор частых ошибок описаны в документации Начало работы с Medusa DTC Starter.

Что дальше

Дальше мы будем поддерживать его в актуальном состоянии, синхронизировать с официальным стартером и обновлять Medusa. Каталог интеграций растёт, и мы будем добавлять в стартер новые провайдеры.

Расскажите, чего не хватает вам. Присоединяйтесь к обсуждению в Telegram-сообществе Medusa или открывайте Issues и Pull Requests на GitHub.