docs: add LICENSE and rewrite README for public release
This commit is contained in:
@@ -1,43 +1,186 @@
|
||||
# Template Plugin
|
||||
# Loop Plugin Starter Template
|
||||
|
||||
Шаблон плагина для LOOP.
|
||||
Стартовый шаблон для разработки плагинов под 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`.
|
||||
|
||||
## Структура проекта
|
||||
|
||||
- `server/` - серверная часть плагина (Go)
|
||||
- `webapp/` - клиентская часть плагина (React/TypeScript)
|
||||
- `plugin.json` - манифест плагина
|
||||
- `plugin.go` - точка входа плагина
|
||||
|
||||
## Установка и сборка
|
||||
|
||||
```bash
|
||||
cd server
|
||||
go mod download
|
||||
|
||||
cd ../webapp
|
||||
yarn install
|
||||
|
||||
cd ..
|
||||
|
||||
make build
|
||||
```
|
||||
├── 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 плагина
|
||||
```
|
||||
|
||||
## Разработка
|
||||
## Что нужно изменить
|
||||
|
||||
Для разработки используйте команды из Makefile:
|
||||
### Серверная часть
|
||||
|
||||
- `make server` - сборка серверной части
|
||||
- `make webapp` - сборка клиентской части
|
||||
- `make dist` - полная сборка плагина
|
||||
- `make check-style` - проверка стиля кода
|
||||
- `make test` - запуск тестов
|
||||
**`server/plugin/plugin.go`** — основная логика:
|
||||
- `OnActivate` — вызывается при включении плагина
|
||||
- `OnDeactivate` — вызывается при выключении
|
||||
|
||||
## Настройка
|
||||
**`server/plugin/api.go`** — REST API:
|
||||
- Добавляйте маршруты в `InitApi()`
|
||||
- Пример маршрута `/example` уже включён
|
||||
|
||||
Измените следующие файлы для настройки плагина:
|
||||
**`server/plugin/configuration.go`** — настройки плагина:
|
||||
- Добавьте поля в структуру `Configuration`
|
||||
- Они будут доступны в панели администратора Loop
|
||||
|
||||
- `plugin.json` - ID, имя и описание плагина
|
||||
- `server/plugin/plugin.go` - основная логика сервера
|
||||
- `webapp/src/index.tsx` - точка входа клиентской части
|
||||
- `webapp/src/components/RootComponent.tsx` - корневой компонент React
|
||||
### Клиентская часть
|
||||
|
||||
**`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)
|
||||
|
||||
Reference in New Issue
Block a user