Настройка и установка Bitrix cli

@bitrix/cli консольный инструмент, основная цель которого, упростить и автоматизировать разработку фронтенда для проектов на Битрикс.

Установка bitrix cli

Для работы @bitrix/cli скачиваем и устанавливаем NodeJs на ту машину, в которой планируется производить сборку.

Для глобальной установки сборщика, выполните команду:

npm install -g @bitrix/cli

Если нужна поддержка SASS, добавляем:

npm install -g @bitrix/cli node-sass

Структура проекта

Все общие файлы, для всего проекта, включая многосайтовость, которые могут быть подключены в разных компонентах или шаблонах, должны обязательно находится в дириктории /local/js/название_проекта. Создаем заготовку расширения, руками или через команду отвечая на вопросы:

bitrix create

Расширение (экстеншн, extension)

Папка local
- Папка js
  - Папка hmarketing
    - Папка up
      - Папка src исходные файлы стилей и скриптов
      - Папка dist готовые бандлы для браузера
      - Файл bundle.config.js конфигурационный файл для сборщика
      - Файл config.php конфигурационный файл экстеншна для системы
Остальные файлы

Компоненты и шаблоны компонентов

myconponent
Папкаlang локализации
Папка templates шаблоны
- Папка .default
  - Файл template.php шаблон компонента
  - Папка src исходные файлы стилей и скриптов
  - Файл bundle.config.js конфигурационный файл для сборщика
  - Файл config.php конфигурационный файл экстеншна для системы
  - Папка lang локализации
  - Файл scripts.js скрипты для браузера
  - Файл style.css стили для браузера
Файл .description.php описания
Файл .parameters.php входные параметры

Расширение (экстеншн, extension)

Файл bundle.config.js

Чтобы bitrix cli работал, нам внутри нашего расширения нужно создать конфигурационный файл bundle.config.js с минимальными настройками:

bundle.config.jsmodule.exports = {
  // файл для которого необходимо выполнить сборку
  input: "./src/script.js",
  // путь к бандлу, который будет создан в результате сборки
  output: {
    js: "./dist/script.bundle.js",
    css: "./dist/style.bundle.css",
  },
  // запрещаем сборщику модифицировать config.php
  adjustConfigPhp: false,
  // включаем минификацию
  minification: true,
  // включаем browserslist
  browserslist: true,
  // неймспейс, в который будут добавлены все экспорты из файла указанного в input
  namespace: 'HM.Bootstrap',
  // сообщит сборщику, что все импорты NPM пакетов необходимо разрешить, тоесть разрезолвить и добавить в бандл
  plugins: {
    resolve: true,
  },
};

Файл config.php

Файл config.php нужен для того чтобы объявить данный скрипт модулем. После этого появится возможность его подключать через ядро, и рантаймить. Файл будет обновляться автоматически по мере необходимости. Например, если в JS коде появится зависимость которая не указана в config.php, то она будет автоматически добавлена в секцию rel. Создаем файл с минимальными настройками:

config.php<?php
if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED !== true) die();
return [
    // путь к js файлу или массив путей, рекомендуется указывать относительный путь
    'js' => './dist/script.bundle.js',
    // путь к css файлу или массив путей, рекомендуется указывать относительный путь
    'css' => './dist/style.bundle.css',
    // список зависимостей (экстеншн, extension), необходимо указать имена расширений, которые должны быть подключены перед подключением текущего расширения, зависимости подключаются рекурсивно и с учетом указанного порядка
    'rel' => [
        'main.core',
	],
    // запрещает подключать main.core автоматически, как зависимость, по умолчанию false — main.core подключается. При сборке бандла значение параметра устанавливается автоматически если в коде нет прямой зависимости на `main.core`
    'skip_core' => false,
];

Компоненты

Файл bundle.config.js

bundle.config.jsmodule.exports = {
  // файл для которого необходимо выполнить сборку
  input: "./src/script.js",
  // путь к бандлу, который будет создан в результате сборки
  output: {
    js: "./script.js",
    css: "./style.css",
  },
  // запрещаем сборщику модифицировать config.php
  adjustConfigPhp: false,
  // включаем минификацию
  minification: true,
  // включаем browserslist
  browserslist: true,
  // неймспейс, в который будут добавлены все экспорты из файла указанного в input
  namespace: 'HM.Bootstrap',
  // сообщит сборщику, что все импорты NPM пакетов необходимо разрешить, тоесть разрезолвить и добавить в бандл
  plugins: {
    resolve: true,
  },
};

Файл config.php

config.php<?php
if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED !== true) die();
return [
    // путь к js файлу или массив путей, рекомендуется указывать относительный путь
    'js' => './script.js',
    // путь к css файлу или массив путей, рекомендуется указывать относительный путь
    'css' => './style.css',
    // список зависимостей (экстеншн, extension), необходимо указать имена расширений, которые должны быть подключены перед подключением текущего расширения, зависимости подключаются рекурсивно и с учетом указанного порядка
    'rel' => [
        'main.core',
	],
    // запрещает подключать main.core автоматически, как зависимость, по умолчанию false — main.core подключается. При сборке бандла значение параметра устанавливается автоматически если в коде нет прямой зависимости на `main.core`
    'skip_core' => false,
];

Все параметры bundle.config.js

bundle.config.jsmodule.exports = {
  // файл для которого необходимо выполнить сборку, необходимо указать относительный путь
  input: "./src/scripts.js",

  // путь к бандлу, который будет создан в результате сборки, обычно это ./dist/<extension_name>.bundle.js, необходимо указать относительный путь
  output: {
    js: "./dist/scripts.bundle.js",
    css: "./dist/style.bundle.css",
  },

  // неймспейс, в который будут добавлены все экспорты из файла указанного в input
  namespace: "BX.Main.Filter",

  // cписки файлов для принудительного объединения. Файлы будут объединены без проверок на дублирование кода, sourcemap's объединяются автоматически, необходимо указать относительные пути
  concat: {
    js: "./src/script.js",
    css: "./src/style.css",
  },

  // разрешает или запрещает сборщику модифицировать config.php, по умолчанию true (разрешено)
  adjustConfigPhp: true,

  // разрешает или запрещает сборщику удалять неиспользуемый код, по умолчанию true (включено)
  treeshake: true,

  // разрешает или запрещает пересобирать бандлы, если сборка запущена не в корне текущего экстеншна, по умолчанию false (разрешено)
  'protected': false,

  // определяет правила Browserslist: false — не использовать (по умолчанию), true — использовать файл .browserslist / .browserslistrc
  browserslist: boolean | string | Array,

  // включает или отключает минификацию, по умолчанию отключено. Может принимать объект настроек Terser: false — не минифицировать (по умолчанию), true — минифицировать с настройками по умолчанию, object — минифицировать с указанными настройками
  minification: boolean | object,

  // включает или отключает преобразование нативных JS классов. По умолчанию значение параметра выставляется автоматически на основании browserslist
  transformClasses: boolean,

  // включает или отключает создание Source Maps файлов
  sourceMaps: boolean,

  //*************************************************//
  // плагины
  //*************************************************//

  plugins: {
    // переопределяет параметры Babel, можно указать собственные параметры Babel https://babeljs.io/docs/en/options, если указать false, то код будет собран без транспиляции
    babel: boolean | Object,

    // дополнительные плагины Rollup, которые будут выполняться при сборке бандлов
    custom: Array | Function,
  },

  //*************************************************//
  // обработки путей к изображениям в CSS
  //*************************************************//

  cssImages: {
    // определяет правило, по которому изображения должны быть обработаны: 'inline' — преобразует изображения в инлайн, 'copy' — копирует изображения в директорию 'output', по умолчанию inline
    type: 'inline' | 'copy',

    // путь к директории, в которую должны быть скопированы используемые изображения
    output: string,

    // максимальный размер изображений в кб, которые могут быть преобразованы в инлайн. По умолчанию 14кб
    maxSize: number,

    // использовать ли svgo для оптимизации svg, по умолчанию true
    svgo: boolean,
  },
  resolveFilesImport: {
    // путь к директории, в которую должны быть скопированы, импортированные изображения
    output: string,

    // определяет разрешенные для импорта типы файлов. По умолчанию ['**/*.svg', '**/*.png', '**/*.jpg', '**/*.gif']
    // https://github.com/isaacs/minimatch
    include: Array,
  },

  //*************************************************//
  // настройки тестов
  //*************************************************//

  tests: {
    // настройки локализации
    localization: {
    // нод языка локализации, по умолчанию 'en'
    languageId: string,

    // включает или выключает автозагрузку фраз в тестах, по умолчанию включено
    autoLoad: boolean,
    },
  },
};

Все параметры config.php

config.phpreturn [
    // путь к css файлу или массив путей, рекомендуется указывать относительный путь
    'css' => String | Array,

    // путь к js файлу или массив путей, рекомендуется указывать относительный путь
    'js' => String | Array,

    // список зависимостей, необходимо указать имена расширений, которые должны быть подключены перед подключением текущего расширения. Зависимости подключаются рекурсивно и с учетом указанного порядка
    'rel' => String | Array,

    // путь к файлу с языковыми фразами или массив путей, файл `lang//config.php` подключается автоматически, его тут можно не указывать
    'lang' => String | Array,

    // запрещает подключать main.core автоматически, как зависимость. По умолчанию false — main.core подключается. При сборке бандла значение параметра устанавливается автоматически если в коде нет прямой зависимости на `main.core`
    'skip_core' => Boolean,

    // обработчик, который вызывается перед подключением расширения на страницу в качестве первого параметра будет передан массив конфигурации расширения обработчик может модифицировать этот массив и вернуть из функции. Это может быть полезно когда необходимо добавить в языковые фразы какие-то данные с сервера
    'oninit' => Function,

    // дополнительные языковые фразы, это может быть полезно для передачи вычисляемых значений языковых фраз, принимает массив. В качестве ключей необходимо указывать идентификаторы языковых фраз
    'lang_additional' => Array, string>,

    // параметр доступен с версии 20.5.100 модуля main. Параметр позволяет указать настройки, которые могут быть получены в JS, с помощью метода Extension.getSettings().
    'settings' => Array
];

Импорт

В директории src следует располагать исходные файлы в формате ES6. Из файлов в данной директории на основании данных файла конфигурации и внутренних ссылок будут созданы финальные версии для подключения в браузере (бандлы) в формате ES5. Внутри файла script.js можно использовать import других файлов из текущей директории или импортировать другие CoreJS расширения.

Если в папке src есть файл file.js и в нем есть экспортируемый класс SomeClass:

script.jsimport {SomeClass} from "./file.js";

Для импорта file.scss:

script.jsimport './file.scss';

Для импорта CoreJS 2.0:

script.jsimport {Loader} from 'main.loader';

Для импорта библиотеки из CoreJS 2.0:

script.jsimport "main.date";

Использование расширений

Подключаем либо в header.php, если функционал необходим на всех страницах сайта, либо в конкретных шаблонах компонента. Если расширение используем в шаблоне компонента тогда вызов делаем в нем, в любых файлах component_epilog.php, template.php, script.js.

В PHP

Метод \Bitrix\Main\UI\Extension::load принимает в качестве параметра имя расширения, либо массив имен:

index.php\Bitrix\Main\UI\Extension::load(['hmarketing.up']);

В JS

Импорт расширения написанного в процедурном стиле, исключением станут экспортируемые функций/классы:

index.jsBX.Runtime.loadExtension('myextensions.test');

Импорт всего расширения, включая код написанный в процедурном стиле и экспортируемые функций/классы:

index.jsBX.Runtime.loadExtension('myextensions.test').then(res => {
    // пространство имен Hmarketing с экспортируемой функцией test()
    Hmarketing.test();
});

В данном случае myextensions.test это расширение которое находится по пути /local/js/myextensions/test/, в файле /local/js/myextensions/test/bundle.config.js задано пространство имен namespace: 'Hmarketing', в файле /local/js/myextensions/test/src/scripts.js экспортируется функция test().

/local/js/myextensions/test/bundle.config.jsmodule.exports = {
    input: "./src/scripts.js",
    output: "./dist/scripts.js",
    adjustConfigPhp: false,
    namespace: 'Hmarketing',
    minification: false,
    browserslist: true,
};

/local/js/myextensions/test/config.php<?php
if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED !== true) die();
return [
    'js' => './dist/scripts.js',
];

/local/js/myextensions/test/src/scripts.js// экспортируемая функция
export function test () {
    console.log('Сработала экспортируемая функция test')
}
// процедурный код
console.log('Сработал процедурный код')

Структура расширения:

Папка local
- Папка js
  - Папка myextensions
    - Папка test
      - Папка dist сгенерированные файлы
      - Папка src файлы источники
      - Файл bundle.config.js
      - Файл config.php
Остальные файлы

Прямой импорт экспортируемой функции test():

index.jsimport {test} from "../../../../../../../local/js/myextensions/test/src/scripts.js";

Команды

Запуск сборки:

bitrix build

Сборщик рекурсивно найдет все файлы bundle.config.js и выполнит для каждого конфига сборку и транспиляцию.

Режим отслеживания изменений, пересобирает бандлы после изменения исходных файлов:

bitrix build --watch

Сокращенный вариант:

bitrix build -w

Вариант с отслеживанием изменений в указанных типах файлов:

bitrix build -w=defaults,json,mjs,svg

defaults набор расширений файлов, которые отслеживаются по умолчанию. defaults равен js, jsx, vue, css, scss.

Запуск режима непрерывного тестирования. Тесты запускаются после каждой сборки. Обратите внимание, сборка с параметром --test выводит в отчете только статус прохождения тестов, прошли или не прошли:

bitrix build --test

Полный отчет по тестам, выводит команда:

bitrix test

Сборка только указанных модулей, поддерживается только в корневой дириктории с модулями local/js и bitrix/modules:

bitrix build --modules main,ui,landing

Запуск сборки для указанной директории, в значении нужно указать относительный путь к директории:

bitrix build --path ./main/install/js/main/loader

Запуск сборки для указанных экстеншнов. В качестве значения нужно указать имя экстеншна, либо список имен через запятую. Команду можно запускать из любой директории проекта:

bitrix build -e=main.core,ui.buttons,landing.main