JavaScript и расширение платформы
Как добавить вычисления, внешние данные, обработчики и интеграции, сохранив серверную разметку и управляемую структуру проекта.

Содержание руководства
- Go-сервисы: API и предметная логика рядом с проектом
- Lego-модули: композиция без монолита
- Сначала декларация, затем код
- Серверный JavaScript
- Внешние данные и фоновые обновления
- Интерактивность в браузере
- Действия, API и Go-сервисы
- Контекст compute и подготовка данных
- Формы и действия модуля
- Какой способ выбрать
Go-сервисы: API и предметная логика рядом с проектом
Когда серверного JavaScript уже мало, вынесите интеграцию в отдельный процесс проекта. Go-сервис получает публичные HTTP-методы, закрытый RPC и события через шину расширений, собирается под нужную платформу и не требует пересборки ядра.
В руководстве есть структура каталога, service.json, рабочие обработчики, правила публичности, проверка запуска и список проверок перед публикацией.
Lego-модули: композиция без монолита
Собирайте сложный блок с серверной отрисовкой из независимых модулей: координатор отвечает за раскладку, владелец состояния остаётся единственным владельцем данных, а модули представления занимают именованные места.
Руководство показывает декларации module.compose.json, точные маркеры серверной отрисовки, атомарную установку через section_add_composed и безопасное поведение при неполной композиции.
Сначала декларация, затем код
Большинство модулей BuildNexus не требуют программирования. Контракт описывает поля, конфигурация указывает шаблон и источник данных, а серверное ядро собирает готовый HTML.
Код нужен, когда появляется действие или вычисление, которое нельзя выразить настройками. Удобное правило:
- показать записи из раздела, коллекции или сущности: объявить источник;
- отфильтровать, отсортировать и ограничить: задать параметры выборки;
- посчитать цену, скидку или подпись: добавить серверный сценарий
compute; - получить данные из внешнего сервиса по расписанию: настроить
refresh; - обработать отправку формы: создать действие модуля;
- собрать сложный блок с серверной отрисовкой: использовать Lego-композицию;
- добавить проектный API, RPC или события: создать отдельный Go-сервис.
Так настройки остаются видимыми Studio и агентам, а код решает только ту часть задачи, где он действительно нужен.
Серверный JavaScript
Серверный JavaScript добавляет модулю вычисления без пересборки ядра. Сейчас выполняются два хука: compute(ctx) готовит данные при отрисовке, а refresh(input) по расписанию получает внешние данные в файловый кеш.
compute не имеет доступа к сети, диску, DOM, import и require. Внешние запросы доступны только в фоновом refresh через безопасные функции bnx.fetch и bnx.head.
Открыть полный справочник по серверному JavaScript: весь ctx, функции bnx, внешние адреса, кеш, ограничения, отладка и шесть практических примеров.
Внешние данные и фоновые обновления
Это продолжение настройки серверного JavaScript из предыдущего раздела. Допустим, модуль называется release_box и должен раз в час получать номер новой версии с внешнего сайта. Настройка затрагивает четыре места внутри папки modules/release_box/.
1. Подключите сценарии в manifest.json
Откройте modules/release_box/manifest.json. Поле runtime находится на верхнем уровне объекта, рядом с name и version. Если runtime уже существует, добавьте в него js, не удаляя остальные настройки.
{
"name": "release_box",
"version": "1.0.0",
"runtime": {
"js": {
"compute": "server/compute.js",
"refresh": "server/refresh.js",
"refresh_every_minutes": 60,
"refresh_hosts": ["updates.example.ru"]
}
}
}refresh_hosts содержит только имена внешних хостов, без https:// и пути. Адрес updates.example.ru из примера нужно заменить адресом вашего источника.
2. Получите данные в server/refresh.js
Создайте файл modules/release_box/server/refresh.js. Именно здесь разрешён внешний запрос:
function refresh(input) {
var url = 'https://updates.example.ru/version.json';
var res = bnx.fetch(url);
if (!res.ok) {
bnx.log('warn', 'Не удалось обновить версию', {
error: res.error
});
return {};
}
var data = res.json();
if (!data || !data.version) return {};
return {
version: String(data.version),
checked_at: bnx.date(new Date(), 'dd.MM.yyyy HH:mm')
};
}Возвращённый объект сохраняется в файловый кеш модуля. При ошибке return {} оставит последний успешный кеш, поэтому кратковременная недоступность чужого сервера не очистит блок.
3. Передайте кеш шаблону через server/compute.js
Создайте или дополните modules/release_box/server/compute.js. Этот код выполняется при показе страницы и не обращается к сети:
function compute(ctx) {
var cached = ctx.cache || {};
return {
version: cached.version || 'Версия уточняется',
checked_at: cached.checked_at || '',
has_version: Boolean(cached.version)
};
}4. Выведите значения в шаблоне модуля
В используемом файле из modules/release_box/templates/ добавьте обычные токены Vue-HTML:
<p>Актуальная версия: {{ version }}</p>
<small v-if="checked_at">
Проверено: {{ checked_at }}
</small>Как запускается обновление
Поле refresh_every_minutes: 60 просит ядро обновлять кеш раз в час. На обычном хостинге планировщик должен регулярно обращаться к /health; без такого задания cron фоновые сценарии не запускаются. До первого успешного обновления посетитель увидит запасной текст «Версия уточняется».
Полный справочник по внешним адресам и refresh содержит правила refresh_hosts, лимиты, работу с JSON, резервные адреса и дополнительные примеры.
Основное размещение — ваш VPS. Для подключения достаточно IP-адреса, логина и пароля от VPS. Studio установит необходимые компоненты и будет управлять сервисами: отдельно заходить на сервер и устанавливать панель управления не требуется. Как подключить VPS в Studio.
Если сложно подключить сервер через мастер или вручную, выберите облако BuildNexus или обратитесь в техническую поддержку за настройкой вашего VPS или хостинга — 2 500 ₽ разово.
Интерактивность в браузере
Серверный JavaScript готовит данные до отправки страницы. Браузерный JavaScript работает уже у посетителя и отвечает за раскрывающиеся панели, вкладки, фильтры, слайдеры и другие реакции на действия.
Простой блок обычно получает небольшой сценарий рядом со своими стилями. Инициализируйте каждый экземпляр по data-section-id, чтобы несколько одинаковых разделов на странице не мешали друг другу.
Для сложного состояния можно использовать Vue 3 как интерактивный остров. Сервер всё равно сначала отдаёт читаемый HTML и начальные данные, а Vue подключается поверх него. Корзина или фильтр становятся удобнее, но основное содержание не исчезает при ошибке загрузки сценария.
Не смешивайте уровни: вычисление цены для шаблона относится к серверному compute, открытие вкладки по клику — к браузерному сценарию, а большая интерактивная область — к Vue-острову.
Действия, API и Go-сервисы
Действие модуля — серверный обработчик конкретной команды: отправки формы, изменения записи или запуска операции. Форма обращается к действию своего модуля и получает структурированный результат.
Публичный API нужен браузерным компонентам и внешним клиентам для разрешённых операций. Доступные поля и команды объявляются явно: внутренний метод не становится публичным автоматически.
Проектный Go-сервис нужен для внешних интеграций, длительной доменной логики, закрытого RPC и событий. Он живёт в sites/app/services/<name>, запускается отдельным процессом и не требует пересборки bnxcore.
Практическая граница: настройка и шаблон входят в модуль; локальное вычисление — в серверный JavaScript; сложный визуальный блок — в Lego-композицию; изолированная бизнес-логика проекта — в Go-сервис.
Контекст compute и подготовка данных
compute(ctx) получает снимок данных одного вызова и возвращает объект токенов для шаблона.
ctx.sectionсодержит то, что фактически заполнил редактор; локальные записи находятся вctx.section.objects.ctx.settingsобъединяет параметры раздела со значениями по умолчанию из контракта.ctx.recordсодержит текущую запись на детальной странице.ctx.scope,ctx.langиctx.page_nameописывают режим отрисовки.ctx.cacheсодержит последний результат фоновогоrefresh.
function compute(ctx) {
var price = Number(ctx.section.price || ctx.settings.price) || 0;
var quantity = Number(ctx.section.quantity || 1);
return {
total: price * quantity,
total_label: bnx.money(price * quantity)
};
}
Поля редактора часто приходят строками, поэтому числа преобразуют явно. Сначала читайте ctx.section, затем значение по умолчанию из ctx.settings, иначе пользовательская настройка может быть незаметно заменена дефолтом.
Объект bnx предоставляет перевод, денежный формат, склонение, даты, именованные URL, разрешённые сущности, хеширование и журнал. Скрипт не должен хранить состояние между вызовами.
Формы и действия модуля
Форма состоит из трёх частей: серверного HTML, браузерного поведения и серверного действия.
- Шаблон выводит подписи, поля, кнопку и доступное сообщение об ошибке.
- Браузерный сценарий собирает значения, блокирует повторную отправку и показывает состояние загрузки.
- Действие модуля проверяет входные данные, выполняет разрешённую операцию и возвращает структурированный ответ.
Для стандартной формы модуль объявляет runtime.action.kind = 'form' в module.compose.json и получает общий приёмник форм без отдельного Go-кода. Это отдельный механизм платформы: объявление runtime.js.action сейчас не запускает JavaScript-хук.
Более сложные команды реализуются поддерживаемым серверным действием или проектным Go-сервисом. Проверять обязательные поля, допустимые значения и права нужно на сервере, даже если браузер уже выполнил свою проверку.
Что должен увидеть пользователь
- какое поле заполнено неверно;
- идёт ли отправка;
- успешно ли принято обращение;
- что делать при временной ошибке.
Перед публикацией проверьте форму без JavaScript, с двойным нажатием, ошибочным телефоном, недоступной почтой и включённой CAPTCHA.
Какой способ выбрать
- Новый информационный блок: контракт, шаблон и стили.
- Сложный блок из готовых секций с серверной отрисовкой: Lego-композиция.
- Список из проекта: коллекция или декларативный источник.
- Расчёт перед отрисовкой:
compute. - Регулярное получение внешнего JSON:
refreshи кеш. - Реакция на клик: браузерный сценарий.
- Сложный интерфейс с состоянием: Vue-остров.
- Отправка формы или изменение данных: действие модуля.
- API, закрытый RPC, события и предметная логика: Go-сервис проекта.
Сначала проверьте, нельзя ли решить задачу контрактом и конфигурацией. Такое решение проще редактировать, переносить и проверять автоматически.
Шаг 7 из 11 — JavaScript и расширение платформы
← Шаг 6. Переменные, коллекции и данные · Шаг 8. IDE и ИИ-агенты →