187 lines
6.7 KiB
Markdown
187 lines
6.7 KiB
Markdown
# Loop Plugin Starter Template
|
||
|
||
Стартовый шаблон для разработки плагинов под Loop.
|
||
|
||
Шаблон включает серверную часть на Go и клиентскую часть на React/TypeScript, настроенный билд через Makefile, пример REST API и базовую структуру Redux store.
|
||
|
||
## Требования
|
||
|
||
| Инструмент | Версия |
|
||
|-----------|--------|
|
||
| Go | 1.21+ |
|
||
| Node.js | 22+ |
|
||
| Yarn | 4.x |
|
||
|
||
## Быстрый старт
|
||
|
||
### 1. Клонировать шаблон
|
||
|
||
```bash
|
||
git clone <url-репозитория> my-plugin
|
||
cd my-plugin
|
||
```
|
||
|
||
### 2. Переименовать плагин
|
||
|
||
Откройте `plugin.json` и замените значения:
|
||
|
||
```json
|
||
{
|
||
"id": "ru.loop.plugin.my-plugin",
|
||
"name": "My Plugin",
|
||
"description": "Описание вашего плагина",
|
||
"version": "0.1.0"
|
||
}
|
||
```
|
||
|
||
### 3. Обновить Go-модуль
|
||
|
||
В `go.mod` замените имя модуля:
|
||
|
||
```
|
||
module git.example.com/your-org/my-plugin
|
||
```
|
||
|
||
Затем обновите все импорты в `server/`:
|
||
|
||
```bash
|
||
find server/ -type f -name "*.go" | xargs sed -i 's|git.wilix.dev/loop/loop-plugin-starter-template|git.example.com/your-org/my-plugin|g'
|
||
```
|
||
|
||
### 4. Установить зависимости и собрать
|
||
|
||
```bash
|
||
# Go-зависимости устанавливаются автоматически при сборке
|
||
|
||
# Webapp-зависимости
|
||
cd webapp && yarn install && cd ..
|
||
|
||
# Полная сборка (server + webapp + bundle)
|
||
make dist
|
||
```
|
||
|
||
Собранный плагин будет в `dist/<plugin-id>-<version>.tar.gz`.
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
├── plugin.json # Манифест плагина (ID, имя, версия)
|
||
├── Makefile # Команды сборки
|
||
├── .env.example # Пример переменных окружения
|
||
│
|
||
├── server/
|
||
│ ├── main.go # Точка входа серверной части
|
||
│ └── plugin/
|
||
│ ├── plugin.go # Основная логика плагина (OnActivate/OnDeactivate)
|
||
│ ├── api.go # HTTP маршруты и обработчики
|
||
│ ├── configuration.go # Конфигурация плагина
|
||
│ ├── store.go # Работа с key-value хранилищем
|
||
│ └── telemetry.go # Телеметрия
|
||
│
|
||
└── webapp/
|
||
└── src/
|
||
├── index.tsx # Точка входа клиентской части
|
||
├── registerApp.tsx # Регистрация компонентов в Loop
|
||
├── components/
|
||
│ └── RootComponent.tsx # Корневой React-компонент
|
||
├── store/
|
||
│ ├── actions.ts # Redux actions
|
||
│ └── reducers.ts # Redux reducers
|
||
└── utils/
|
||
├── api.ts # Запросы к серверной части плагина
|
||
└── usePlugin.ts # Хук для доступа к API плагина
|
||
```
|
||
|
||
## Что нужно изменить
|
||
|
||
### Серверная часть
|
||
|
||
**`server/plugin/plugin.go`** — основная логика:
|
||
- `OnActivate` — вызывается при включении плагина
|
||
- `OnDeactivate` — вызывается при выключении
|
||
|
||
**`server/plugin/api.go`** — REST API:
|
||
- Добавляйте маршруты в `InitApi()`
|
||
- Пример маршрута `/example` уже включён
|
||
|
||
**`server/plugin/configuration.go`** — настройки плагина:
|
||
- Добавьте поля в структуру `Configuration`
|
||
- Они будут доступны в панели администратора Loop
|
||
|
||
### Клиентская часть
|
||
|
||
**`webapp/src/registerApp.tsx`** — регистрация в Loop:
|
||
- Регистрация Redux reducer
|
||
- Регистрация React-компонентов через `registry`
|
||
|
||
**`webapp/src/components/RootComponent.tsx`** — основной компонент:
|
||
- Точка входа для отображения вашего UI
|
||
|
||
**`webapp/i18n/`** — переводы:
|
||
- `en.json` — английские строки
|
||
- `ru.json` — русские строки
|
||
|
||
## Makefile: команды сборки
|
||
|
||
```bash
|
||
make dist # Полная сборка (server + webapp + tar.gz)
|
||
make server # Только серверная часть
|
||
make webapp # Только клиентская часть
|
||
make check-style # Линтинг (golangci-lint + eslint)
|
||
make test # Запуск тестов
|
||
make clean # Очистить артефакты сборки
|
||
make deploy # Сборка и деплой на сервер (требует .env)
|
||
make watch # Сборка + hot reload webapp
|
||
```
|
||
|
||
Полный список команд: `make help`
|
||
|
||
## Переменные окружения
|
||
|
||
Скопируйте `.env.example` в `.env` и заполните:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
| Переменная | Описание |
|
||
|-----------|----------|
|
||
| `MM_SERVICESETTINGS_SITEURL` | URL вашего Loop-сервера (для деплоя) |
|
||
| `MM_ADMIN_TOKEN` | Токен администратора (для деплоя через `make deploy`) |
|
||
| `MM_SERVICESETTINGS_ENABLEDEVELOPER` | `true` — билд только под текущую ОС (ускоряет разработку) |
|
||
| `MM_DEBUG` | `true` — билд без оптимизаций (для отладчика dlv) |
|
||
|
||
## Деплой
|
||
|
||
### Ручной деплой
|
||
|
||
1. Соберите плагин: `make dist`
|
||
2. Загрузите `dist/<plugin-id>-<version>.tar.gz` в Loop:
|
||
**Администрирование → Управление плагинами → Загрузить плагин**
|
||
|
||
### Деплой через `make deploy`
|
||
|
||
Требует заполненного `.env` с `MM_SERVICESETTINGS_SITEURL` и `MM_ADMIN_TOKEN`:
|
||
|
||
```bash
|
||
make deploy
|
||
```
|
||
|
||
### CI/CD
|
||
|
||
В директории `.gitea/workflows/` есть пример workflow для Gitea Actions.
|
||
Адаптируйте его под вашу CI/CD систему.
|
||
|
||
## Отладка
|
||
|
||
Для удалённой отладки серверной части с помощью [Delve](https://github.com/go-delve/delve):
|
||
|
||
```bash
|
||
MM_DEBUG=true make deploy # Билд без оптимизаций
|
||
make attach-headless # Attach dlv на порт 2346
|
||
```
|
||
|
||
## Лицензия
|
||
|
||
[MIT](LICENSE)
|