Перейти к содержанию

Инструмент @bitrix/cli

Описание

@bitrix/cli — консольный инструмент Битрикс-разработчика. Основная цель — упростить и автоматизировать разработку фронтенда для проектов на 1С-Битрикс: Управление Сайтом и Битрикс24.

@bitrix/cli - это набор консольных команд:

  1. bitrix build для сборки и транспиляции

Транспиляция — это перевод исходного кода с одного языка на другой. ES6+ кода в кросс-браузерный ES5; 2. bitrix test для запуска Mocha

Mocha (Мока) — JavaScript тест-фреймворк, который можно запускать как на node.js, так и в браузере, удобен для асинхронного тестирования. Тесты Mocha запускаются серийно, позволяя гибко и точно создавать отчеты.

Подробнее... -тестов; 3. bitrix create для быстрого создания расширения

Расширение (экстеншн, extension) — способ организации JS и CSS кода в продукте.

Подробнее... («экстеншна»).

Примечание: В первую очередь @bitrix/cli предназначен для работы с расширениями («экстеншнами»), шаблонами сайта и шаблонами компонентов.

Установка

  • NPM:

npm — менеджер пакетов, входящий в состав Node.js.

Подробнее...

$ npm install -g @bitrix/cli
- YARN:

Yarn — это новый менеджер пакетов, созданный совместно Facebook*, Google, Exponent и Tilde.

* Социальная сеть признана экстремистской и запрещена на территории Российской Федерации.

Подробнее...

$ yarn global add @bitrix/cli

Конфигурация

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

module.exports = {
  input: './app.js', 
  output: './dist/app.bundle.js',
};
- Все параметры:

module.exports = {
  // Файл, для которого необходимо выполнить сборку. 
  // Необходимо указать относительный путь 
  input: string, 

  // Путь к бандлу, который будет создан в результате сборки. 
  // Обычно это ./dist/<extension_name>.bundle.js
  // Необходимо указать относительный путь 
  output: string || {js: string, css: 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>,
  },
    // Определяет правила обработки путей к изображениям в CSS
    // Доступно с версии 3.0.0
    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>,

        // По умолчанию []
        exclude: Array<string>,
    },

    // Определяет правила 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,

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

Подробнее о структуре расширений читайте в соответствующем уроке.

Расширение (экстеншн, extension) — способ организации JS и CSS кода в продуктах 1С-Битрикс: Управление Сайтом и Битрикс24.

Подробнее...

Сборка

Для запуска сборки выполните команду:

$ bitrix build

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

Дополнительные параметры:

  • --watch [[, ...]], -w=[[, ...]]

Режим отслеживания изменений. Пересобирает бандлы

Бандл (bundle, комплект/набор) - это совокупность каких-либо программных данных (файлов), объеденных по какому-либо признаку. В данном случае бандлы — это обработанные и объединенные исходные файлы. после изменения исходных файлов. В качестве значения можно указать список расширений файлов, в которых нужно отслеживать изменения.

$ bitrix build --watch

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

$ bitrix build -w

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

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

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

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

$ bitrix build --test
- --modules [, ...], -m=[, ...]

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

$ bitrix build --modules main,ui,landing
- --path , -p=

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

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

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

$ bitrix build -p=./main/install/js/main/loader
- --extensions [, ...], -e=[, ...]

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

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

Запуск тестов

Команда запускает Mocha-тесты и выводит подробный отчет о прохождении тестов.

$ bitrix test

Примечание: Тестами считаются JS файлы, расположенные в директории ./test относительно файла bundle.config.js. В момент запуска тестов исходный код и код тестов на лету обрабатывается сборщиком и после чего выполняется. Поэтому тесты можно писать на ES6+.

Дополнительные параметры:

  • --watch [[, ...]], -w=[[, ...]]

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

$ bitrix test --watch

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

$ bitrix test -w

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

$ bitrix test -w=defaults,json,mjs,svg

Примечание: defaults – набор расширений файлов, которые отслеживаются по умолчанию. Он равен js,jsx,vue,css,scss. - --modules [, ...], -m=[, ...]

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

$ bitrix test --modules main,ui,landing
- --path , -p=

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

$ bitrix test --path ./main/install/js/main/loader.

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

$ bitrix test -p=./main/install/js/main/loader
- --extensions [, ...], -e=[, ...]

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

$ bitrix test -e=main.core,ui.buttons,landing.main

Создание расширения

Для создания расширения ("экстеншна"):

  • Перейдите в директорию **local/js/

{module} – должно быть без точек в названии, например, партнерский префикс. Подробнее...** - Выполните команду bitrix create. После выполнения команды создаётся папка расширения, например, /ext, и подключается так: \Bitrix\Main\UI\Extension::load("partner.ext"); для пути local/js/partner/ext/. - Ответьте на вопросы мастера

Примечание: Можно не переходить в /{module}. Останьтесь в local/js/, выполните в bitrix create расширение myext и загрузите его \Bitrix\Main\UI\Extension::load("myext");.