docs: add LICENSE and rewrite README for public release
This commit is contained in:
@@ -0,0 +1,21 @@
|
|||||||
|
MIT License
|
||||||
|
|
||||||
|
Copyright (c) 2026 Wilix
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
@@ -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 # Манифест плагина (ID, имя, версия)
|
||||||
- `plugin.json` - манифест плагина
|
├── Makefile # Команды сборки
|
||||||
- `plugin.go` - точка входа плагина
|
├── .env.example # Пример переменных окружения
|
||||||
|
│
|
||||||
## Установка и сборка
|
├── server/
|
||||||
|
│ ├── main.go # Точка входа серверной части
|
||||||
```bash
|
│ └── plugin/
|
||||||
cd server
|
│ ├── plugin.go # Основная логика плагина (OnActivate/OnDeactivate)
|
||||||
go mod download
|
│ ├── api.go # HTTP маршруты и обработчики
|
||||||
|
│ ├── configuration.go # Конфигурация плагина
|
||||||
cd ../webapp
|
│ ├── store.go # Работа с key-value хранилищем
|
||||||
yarn install
|
│ └── telemetry.go # Телеметрия
|
||||||
|
│
|
||||||
cd ..
|
└── webapp/
|
||||||
|
└── src/
|
||||||
make build
|
├── 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` - сборка серверной части
|
**`server/plugin/plugin.go`** — основная логика:
|
||||||
- `make webapp` - сборка клиентской части
|
- `OnActivate` — вызывается при включении плагина
|
||||||
- `make dist` - полная сборка плагина
|
- `OnDeactivate` — вызывается при выключении
|
||||||
- `make check-style` - проверка стиля кода
|
|
||||||
- `make test` - запуск тестов
|
|
||||||
|
|
||||||
## Настройка
|
**`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/registerApp.tsx`** — регистрация в Loop:
|
||||||
- `webapp/src/components/RootComponent.tsx` - корневой компонент React
|
- Регистрация 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