Начало работы с Medusa DTC Starter

В этом руководстве вы узнаете, как установить Medusa DTC Starter от Gorgo, настроить оба приложения и подключить первую интеграцию.

• Node.js v20 или новее
• PostgreSQL v15 или новее
• npm, yarn или pnpm

Установите стартер одним из двух способов: разверните новый проект через собственный CLI Medusa либо клонируйте репозиторий и настройте каждое приложение вручную.

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

--repo-url указывает create-medusa-app разворачивать проект из указанного репозитория вместо официального стартера Medusa, но обычные запросы про имя проекта и базу данных остаются такими же. По умолчанию команда также запускает миграции, создаёт администратора и засеивает базу данных. Передайте --no-migrations, чтобы пропустить все три шага.

1. Клонируйте репозиторий и установите зависимости:

   yarnpnpmnpm

   1git clone https://github.com/gorgojs/medusa-dtc-starter.git
   2cd medusa-dtc-starter
   3yarn install

2. Создайте файл переменных окружения бэкенда и укажите в DATABASE_URL реальную базу данных:

   Terminal
   cp apps/backend/.env.template apps/backend/.env

   apps/backend/.env
   DATABASE_URL=postgres://postgres:@localhost:5432/medusa-dtc-starter

3. Запустите миграции, создайте администратора, загрузите начальные данные и запустите бэкенд:

   yarnpnpmnpm

   1cd apps/backend
   2yarn medusa db:migrate
   3yarn medusa user -e admin@medusajs.com -p supersecret
   4yarn seed
   5yarn dev

4. Откройте панель администратора по адресу http://localhost:9000/app, войдите и скопируйте публикуемый API-ключ в Настройки → Публикуемые API-ключи.

5. Создайте файл переменных окружения витрины с этим ключом:

   Terminal
   cp apps/storefront/.env.template apps/storefront/.env.local

   apps/storefront/.env.local
   NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_6c3...

6. Запустите витрину:

   yarnpnpmnpm

   1cd apps/storefront
   2yarn dev

Витрина запускается на http://localhost:8000. Корень репозитория настроен под pnpm, поэтому pnpm dev оттуда поднимает оба приложения сразу. С npm или yarn запускайте каждое приложение из его собственной папки.

Перед запуском бэкенда нужно задать реальное значение для DATABASE_URL и INTEGRATION_ENCRYPTION_KEY:

apps/backend/.env
1DATABASE_URL=postgres://postgres:@localhost:5432/medusa-dtc-starter
2INTEGRATION_ENCRYPTION_KEY=supersecret

Остальные переменные в apps/backend/.env.template уже заданы рабочими значениями для localhost, кроме блока SMTP, в котором указан условный хост, пока вы не заполните его своим. Что делают остальные переменные:

Смените все значения supersecret перед продакшеном.

Для витрины нужен как минимум публикуемый API-ключ вашего бэкенда:

apps/storefront/.env.local
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_6c3...

Остальные переменные уже заданы рабочими значениями по умолчанию для localhost:

Модуль интеграций (@gorgo/medusa-integration) уже зарегистрирован в medusa-config.ts с пустым массивом providers, так что перед добавлением интеграции ничего дополнительно подключать не нужно. Когда бэкенд запущен, добавьте платёжную, логистическую или ERP-интеграцию и настройте ее из Medusa Admin, читайте в документации Поиск и добавление интеграции.

В логах витрины видна ошибка:

Логи витрины
Error fetching regions. Did you set up regions in your Medusa Admin and define a NEXT_PUBLIC_MEDUSA_BACKEND_URL environment variable.

Причина одна из двух: либо NEXT_PUBLIC_MEDUSA_BACKEND_URL не задан или указывает не туда, либо на бэкенде пока не настроен ни один регион. Проверьте, что бэкенд запущен и доступен по этому адресу. Если регионов правда нет, их создаёт seed-скрипт, читайте в документации Настройка начальных данных.

В логах витрины видна одна из двух ошибок:

Логи витрины
Stripe key is missing. Set NEXT_PUBLIC_STRIPE_KEY environment variable.

Первая означает, что витрина попыталась отрисовать Stripe Elements без публикуемого ключа Stripe.

Логи витрины
Stripe client secret is missing. Cannot initialize Stripe.

Вторая означает, что для корзины ещё не создана платёжная сессия Stripe, обычно потому что в выбранном регионе не настроен провайдер Stripe.

Новый посетитель попадает в регион, никак не связанный с его местоположением, обычно каждый раз в один и тот же.

Задайте GEOLOCATION_DEBUG=true в apps/storefront/.env.local, перезагрузите страницу и прочитайте заголовки x-geo-* на запросе документа в панели сети браузера. x-geo-source называет, что дало ответ: cookie означает, что cookie _medusa_country не была удалена, тогда удалите её или откройте новое приватное окно; fallback-first означает, что определить страну не удалось, а NEXT_PUBLIC_DEFAULT_REGION тоже не совпала ни с одним регионом из seed-данных, тогда задайте в ней реальный код страны; x-geo-provider: platform означает, что переменная GEOLOCATION_PROVIDER не дошла до сервера. Что означает каждый заголовок, читайте в документации Настройка определения страны.

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

STORE_CORS, ADMIN_CORS и AUTH_CORS в .env бэкенда задают списки разрешённых источников. Если вы переносите витрину или Admin на другой порт или домен, добавьте этот адрес в соответствующую переменную и перезапустите бэкенд.