22.07.2025

Создание JS-расширения для Битрикс с Bitrix CLI

В этой статье мы создадим собственное JS-расширение для 1С-Битрикс с использованием современного инструмента @bitrix/cli. В качестве примера реализуем простое приложение "Калькулятор".

Для кого это руководство: начинающие и опытные битрикс-разработчики, которые хотят освоить современный подход к организации фронтенда в Битрикс.

1. Установка и настройка окружения

1.1. Установка Node.js и Bitrix CLI

Перед началом работы необходимо:

Установить Node.js (LTS-версию)
Установить Bitrix CLI глобально:

npm install -g @bitrix/cli

1.2. Подготовка структуры проекта

Расширения в Битрикс располагаются в:

/local/js/ – для кастомных расширений
/bitrix/js/ – для стандартных модулей

Создадим папку для нашего расширения:

mkdir -p /local/js/demo/calculator
cd /local/js/demo/calculator

2. Создание расширения через Bitrix CLI

2.1. Инициализация проекта

Запустим команду:

bitrix create

Ответим на вопросы мастера:

Extension name: demo.calculator
Input file: ./src/calculator.js
Output JS: ./dist/calculator.bundle.js
Output CSS: ./dist/styles.bundle.css
Namespace: Demo.Calculator

После этого Bitrix CLI создаст структуру:

/local/js/demo/calculator/
├── src/
│   └── calculator.js      # Исходный код
├── dist/                  # Собранные файлы
├── bundle.config.js       # Конфиг сборки
└── config.php             # Конфиг расширения

2.2. Настройка bundle.config.js

module.exports = {
  input: "./src/calculator.js",
  output: {
    js: "./dist/calculator.bundle.js",
    css: "./dist/styles.bundle.css",
  },
  namespace: "Demo.Calculator",
  adjustConfigPhp: false,
  minification: true,
  browserslist: true,
  plugins: {
    resolve: true,
  },
};

2.3. Настройка config.php

<?php
if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED !== true) die();

return [
    'js' => './dist/calculator.bundle.js',
    'css' => './dist/styles.bundle.css',
    'rel' => ['main.core'], // Зависимости
    'skip_core' => false,
];

3. Разработка функционала калькулятора

3.1. Пишем логику (src/calculator.js)

// Экспортируем класс калькулятора
export class Calculator {
  static add(a, b) {
    return a + b;
  }

  static subtract(a, b) {
    return a - b;
  }
}

// Процедурный код для интеграции в BX
BX.Demo = BX.Demo || {};
BX.Demo.Calculator = Calculator;

// Пример использования в шаблоне
document.addEventListener('DOMContentLoaded', () => {
  const result = Calculator.add(5, 3);
  console.log('5 + 3 =', result);
});

3.2. Добавляем стили (src/styles.scss)

.calculator-result {
  font-size: 18px;
  color: #333;
  padding: 10px;
  background: #f5f5f5;
  border-radius: 4px;
}

Импортируем стили в calculator.js:

import './styles.scss';

4. Сборка и подключение расширения

4.1. Запуск сборки

bitrix build

Или для автоматической пересборки:

bitrix build --watch

4.2. Подключение в шаблоне сайта

Добавим в header.php или шаблон компонента:

<?php
\Bitrix\Main\UI\Extension::load('demo.calculator');
?>

4.3. Использование в JavaScript

// Через BX (процедурный стиль)
const result = BX.Demo.Calculator.add(10, 5);
console.log('10 + 5 =', result);

// Через ES6-импорт (если используется сборка)
import { Calculator } from 'demo.calculator';
console.log('8 - 3 =', Calculator.subtract(8, 3));

5. Итог

✅ Мы создали JS-расширение для Битрикс с:

Поддержкой ES6+
SCSS-препроцессингом
Автоматической сборкой через Bitrix CLI
Подключением через Extension::load()

Готовый пример можно доработать, добавив:

Взаимодействие с DOM (кнопки, формы)
Локализацию через lang/
Интеграцию с REST API

Дополнительные возможности Bitrix CLI

Команда	Описание
`bitrix build --watch`	Автоматическая пересборка
`bitrix build -p ./`	Сборка проекта с указанием пути
`bitrix test`	Запуск тестов
`bitrix create --help`	Справка по созданию расширений