loop-plugin-starter-template/README.md

Loop Plugin Starter Template

Стартовый шаблон для разработки плагинов под Loop.

Шаблон включает серверную часть на Go и клиентскую часть на React/TypeScript, настроенный билд через Makefile, пример REST API и базовую структуру Redux store.

Требования

Инструмент	Версия
Go	1.21+
Node.js	22+
Yarn	4.x

Быстрый старт

1. Клонировать шаблон

git clone <url-репозитория> my-plugin
cd my-plugin

2. Переименовать плагин

Откройте plugin.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/:

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. Установить зависимости и собрать

# 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: команды сборки

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 и заполните:

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:

make deploy

CI/CD

В директории .gitea/workflows/ есть пример workflow для Gitea Actions. Адаптируйте его под вашу CI/CD систему.

Отладка

Для удалённой отладки серверной части с помощью Delve:

MM_DEBUG=true make deploy   # Билд без оптимизаций
make attach-headless         # Attach dlv на порт 2346

Лицензия

MIT