Локальная настройка API
Это руководство проведёт вас через настройку API ChurchApps для локальной разработки. Вы клонируете репозиторий, настроите подключения к базам данных, инициализируете схему и запустите сервер разработки с горячей перезагрузкой.
Перед началом
- Установите Node.js 24+, Git и MySQL 8.0+ — см. Требования
- Создайте пользователя MySQL с правом создания баз данных
- Ознакомьтесь со справочником Переменные окружения для настройки API
Пошаговая настройка
1. Клонируйте репозиторий
git clone https://github.com/ChurchApps/Api.git
2. Установите зависимости
Проект использует Yarn (защита блокирует npm install):
cd Api
yarn install
3. Настройте переменные окружения
cp .env.sample .env
Откройте .env и настройте строки подключения к MySQL. Каждому модулю нужно собственное подключение к базе данных в следующем формате:
mysql://root:password@localhost:3306/dbname
Понадобятся строки подключения для всех шести баз данных модулей (membership, attendance, content, giving, messaging, doing).
4. Инициализируйте базы данных
npm run initdb
Эта команда автоматически создаёт все шесть баз данных и их таблицы.
Инициализировать базу данных одного модуля можно командой npm run initdb -- --module=membership (или attendance, content, giving, messaging, doing).
5. Запустите сервер разработки
npm run dev
API запустится с горячей перезагрузкой по адресу http://localhost:8084.
Основные команды
| Команда | Описание |
|---|---|
npm run dev | Запуск сервера разработки с горячей перезагрузкой (tsx watch) |
npm run build | Очистка, компиляция TypeScript и копирование ресурсов |
npm run test | Запуск тестов с Jest (включая покрытие) |
npm run test:watch | Запуск тестов в режиме наблюдения |
npm run lint | Запуск ESLint с автоисправлением (ESLint — единственный форматировщик) |
Развёртывание
Окружение staging выведено из эксплуатации. API развёртывается в демо-окружение при каждом push в main, а в продакшн — через ручной workflow Deploy Prod, который также применяет ожидающие миграции базы данных. Подробности см. в Развёртывание API.
Разработка общих библиотек локально
Если нужно разрабатывать общую библиотеку (@churchapps/helpers или @churchapps/apihelper) вместе с API, соберите её в рабочем пространстве Packages и добавьте временную связь Yarn в API:
# В рабочем пространстве Packages
yarn build
# В каталоге API
yarn link ../Packages/helpers
# ... тестирование ...
yarn unlink ../Packages/helpers && yarn install
Так можно проверить изменения библиотеки на API, не публикуя их в npm. Подробности см. в разделе Общие библиотеки — и никогда не коммитьте связь с локальной версией, которую команда записывает в package.json.
Связанные статьи
- База данных — архитектура «одна база на модуль»
- Структура модулей — как организованы контроллеры, репозитории и модели
- Общие библиотеки — работа с
@churchapps/helpersи@churchapps/apihelper