Быстрый старт: первый плагин

За 15–20 минут вы соберёте плагин из готового шаблона и установите его в Loop. Код писать не придётся — цель в том, чтобы убедиться, что всё настроено, и понять цикл «изменил → собрал → установил».

Что понадобится

Программы на компьютере

Программа	Версия	Как проверить	Зачем
Git	любая	`git --version`	Скачать шаблон
Go	1.24 или новее	`go version`	Собрать серверную часть
Node.js	22 или новее	`node -v`	Собрать клиентскую часть
Yarn	4.x	`yarn -v`	Установить зависимости клиентской части
`make`	любая	`make -v`	Запускать команды сборки

Если какой-то команды нет, установите программу по ссылке. Несколько подсказок:

Yarn 4 проще всего включить через Corepack, который идёт вместе с Node.js: выполните corepack enable, и Yarn нужной версии скачается сам.
make на macOS ставится вместе с инструментами разработчика: xcode-select --install.
На Windows удобнее всего работать в WSL (Ubuntu внутри Windows) — все команды из этого раздела там работают как есть.

Сервер Loop для экспериментов

Нужен Loop, в котором вы системный администратор. Лучше всего — отдельный тестовый сервер, а не рабочий: во время разработки плагин будет часто перезапускаться.

На сервере должна быть разрешена загрузка плагинов. По умолчанию она выключена, и в Системной консоли её не включить — только в конфигурации сервера. Попросите администратора сервера сделать одно из двух и перезапустить Loop:

в файле config.json установить "EnableUploads": true в разделе PluginSettings;
или задать переменную окружения MM_PLUGINSETTINGS_ENABLEUPLOADS=true.

Проверить просто: откройте Системная консоль > Плагины > Управление плагинами. Если есть кнопка Выбрать файл — загрузка включена. Если вместо неё написано «Включите загрузку плагинов в config.json» — нет.

На той же странице должно быть Требовать подпись плагина: Нет. Если там Да, Loop принимает только подписанные плагины из магазина, и загрузить свой не получится.

Шаг 1. Скачайте шаблон

Для плагинов Loop есть стартовый шаблон. Это полностью рабочий пустой плагин: в нём уже настроены сборка, серверная и клиентская части. Скачайте его в папку my-plugin:

git clone https://git.wilix.dev/loop/loop-plugin-starter-template.git my-plugin
cd my-plugin

Отвяжите папку от репозитория шаблона, чтобы вести в ней свою историю изменений:

rm -rf .git
git init

Шаг 2. Дайте плагину имя

Откройте файл plugin.json в корне проекта и поменяйте четыре поля:

{
    "id": "ru.mycompany.hello",
    "name": "Hello",
    "description": "Мой первый плагин",
    "version": "0.1.0",
    ...
}

Поле	Что писать
`id`	Уникальный идентификатор. Удобно брать домен компании задом наперёд и добавлять название: `ru.mycompany.hello`. Только латиница, цифры, `.`, `-` и `_`. После первой установки не меняйте — иначе Loop будет считать это другим плагином
`name`	Название, которое увидит администратор в списке плагинов
`description`	Одна-две фразы о том, что делает плагин
`version`	Версия в формате `major.minor.patch`, например `0.1.0`

Остальные поля пока не трогайте, о них — в разделе Манифест.

Шаг 3. Переименуйте Go-модуль

Серверная часть написана на Go, и у неё есть своё имя модуля — сейчас это адрес шаблона. Замените его на адрес вашего репозитория (или любое имя вида example.com/hello, если репозитория пока нет).

В файле go.mod поменяйте первую строку:

module git.mycompany.ru/team/hello

Затем замените старое имя во всех импортах серверного кода:

# macOS
grep -rl 'git.wilix.dev/loop/loop-plugin-starter-template' server build | \
  xargs sed -i '' 's|git.wilix.dev/loop/loop-plugin-starter-template|git.mycompany.ru/team/hello|g'

# Linux и WSL
grep -rl 'git.wilix.dev/loop/loop-plugin-starter-template' server build | \
  xargs sed -i 's|git.wilix.dev/loop/loop-plugin-starter-template|git.mycompany.ru/team/hello|g'

подсказка

Этот шаг можно пропустить, пока вы просто пробуете: плагин соберётся и со старым именем. Но перед тем как публиковать код, переименуйте модуль.

Шаг 4. Соберите плагин

Установите зависимости клиентской части (один раз) и запустите сборку:

cd webapp && yarn install && cd ..
make dist

Первая сборка занимает несколько минут: Go и Yarn скачивают библиотеки. Если всё прошло хорошо, в конце появится строка:

plugin built at: dist/ru.mycompany.hello-0.1.0.tar.gz

Это и есть готовый плагин.

подсказка

make без параметров

Команда make делает то же самое, но сначала проверяет стиль кода и запускает тесты. Для проверки Go-кода ей нужен golangci-lint: установите его командой make deps (или brew install golangci-lint на macOS).

Шаг 5. Установите плагин в Loop

Через Системную консоль

Откройте Системная консоль > Плагины > Управление плагинами.
В блоке Загрузить плагин нажмите Выбрать файл и выберите dist/ru.mycompany.hello-0.1.0.tar.gz.
Нажмите Загрузить.
Найдите плагин в списке Установленные плагины и нажмите Включить.

Через несколько секунд под плагином появится надпись Этот плагин работает.

Командой `make deploy`

Загружать файл руками при каждом изменении быстро надоедает. Шаблон умеет делать это сам:

Создайте персональный токен доступа для своей учётной записи системного администратора.

Скопируйте файл настроек и заполните его:

cp .env.example .env

.env
MM_SERVICESETTINGS_SITEURL=https://your-loop-server.ru
MM_ADMIN_TOKEN=ваш-токен

Выполните:
```
make deploy
```

Команда соберёт плагин, загрузит его на сервер и включит. Теперь цикл разработки выглядит так: изменили код → make deploy → обновили страницу Loop.

warning

Файл .env — только на вашем компьютере

В .env лежит токен администратора. Файл уже добавлен в .gitignore — не удаляйте его оттуда и не отправляйте токен в репозиторий.

Шаг 6. Проверьте, что плагин работает

В Системная консоль > Плагины > Управление плагинами под плагином написано Этот плагин работает.
Откройте в браузере, где вы вошли в Loop, адрес:
```
https://your-loop-server.ru/plugins/ru.mycompany.hello/example
```
Вы увидите ответ серверной части плагина:
```
{"status":"OK","data":{"message":"Hello from template plugin"}}
```

Если так и есть — поздравляем, всё настроено. Если нет, загляните в раздел Отладка и частые ошибки.

Что дальше

Пошаговый пример: превратим шаблон в плагин с ботом, slash-командой, настройками и панелью в интерфейсе.
Устройство проекта: что лежит в каждой папке шаблона и какие команды есть в Makefile.

Что понадобится​

Программы на компьютере​

Сервер Loop для экспериментов​

Шаг 1. Скачайте шаблон​

Шаг 2. Дайте плагину имя​

Шаг 3. Переименуйте Go-модуль​

Шаг 4. Соберите плагин​

Шаг 5. Установите плагин в Loop​

Через Системную консоль​

Командой make deploy​

Шаг 6. Проверьте, что плагин работает​

Что дальше​