Настройка и установка 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

Общие

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

Компоненты

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

Файл bundle.config.js

Конфигурационный файл для сборщика.

Базовая конфигурация

Все стили должны подключаться в файле /src/script.js, за счет импорта import "./style.css", в этом случае файл style.css должен находится в одной дириктории с script.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,
  },
};

Все параметры

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<string>,
  
  // включает или отключает минификацию, по умолчанию отключено. Может принимать объект настроек 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<string | 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<string>,
  },
    
  //*************************************************//
  // настройки тестов                               
  //*************************************************// 

  tests: {
    // настройки локализации 
    localization: {
    // нод языка локализации, по умолчанию 'en'
    languageId: string,
    
    // включает или выключает автозагрузку фраз в тестах, по умолчанию включено 
    autoLoad: boolean,
    },
  },
};

Файл config.php

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

При использовании @bitrix/cli файл config.php будет создан автоматически при сборке и будет обновляться автоматически по мере необходимости. Например, если в JS коде появится зависимость которая не указана в config.php, то она будет автоматически добавлена в rel.

Базовая конфигурация

config.php<?php
if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED !== true) die();
return [
    'js' => './dist/script.bundle.js',
    'css' => './dist/style.bundle.css',
];

Все параметры

config.phpmodule.exports = {
    // файл, для которого необходимо выполнить сборку, обычно это './src/<extension>.js, необходимо указать относительный путь 
    input: string, 
    // путь к бандлу, который будет создан в результате сборки, обычно это ./dist/<extension>.bundle.js, необходимо указать относительный путь 
    output: string,
    // неймспейс, в который будут добавлены все экспорты из файла указанного в input, например 'BX.Main.Filter'
    namespace: string,
    // списки файлов для принудительного объединения, файлы будут объединены без проверок на дублирование кода, sourcemap's объединяются автоматически, необходимо указать относительные пути
    concat: {
    js: Array<string>,
    css: Array<string>,
    },
    // разрешает или запрещает сборщику модифицировать config.php, по умолчанию true (разрешено)
    adjustConfigPhp: boolean,
    // разрешает или запрещает сборщику удалять неиспользуемый код, по умолчанию true (включено)
    treeshake: boolean,
    // разрешает или запрещает пересобирать бандлы, если сборка запущена не в корне текущего экстеншна, по умолчанию false (разрешено)
    'protected': boolean,
    plugins: {
        // переопределяет параметры Babel, можно указать собственные параметры Babel, https://babeljs.io/docs/en/options, если указать false, то код будет собран без транспиляции
        babel: boolean | Object,
        // дополнительные плагины Rollup, которые будут выполняться при сборке бандлов 
        custom: Array<string | Function>,
    },
};

Импорт

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

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

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

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

script.jsimport './file.css';

Для импорта 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.jsimport {Loader} from 'main.loader';

Если вы хотите импортировать старое расширение (не поддерживающие import ES6, например main.date), укажите импорт без экспорта расширения:

index.jsimport "main.date";

Когда вы импортируете расширение в JS, сборщик автоматически добавляет это расширение как зависимость в config.php.

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

script.jsimport {Runtime} from 'main.core';
Runtime.loadExtension('main.loader').then((exports) => {
    // код, который использует main.loader, в exports будут все экспорты из main.loader
});

Команды

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

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