@bitrix/cli

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

Содержание

Описание
Установка
Конфигурация
Сборка
Запуск тестов
Создание экстеншна

Описание

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

bitrix build для сборки и транспиляции ES6+ кода
bitrix test для запуска Mocha тестов
bitrix create для быстрого создания «экстеншна»

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

Установка

NPM

$ npm install -g @bitrix/cli

YARN

$ 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,
        },
    },
};

Сборка

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

$ bitrix build

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

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

--watch [\<fileExtension>[, ...]], -w=[\<fileExtension>[, ...]]

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

$ 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 \<moduleName>[, ...], -m=\<moduleName>[, ...]

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

$ bitrix build --modules main,ui,landing

--path \<path>, -p=\<path>

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

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

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

$ bitrix build -p=./main/install/js/main/loader

--extensions \<extensionName>[, ...], -e=\<extensionName>[, ...]

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

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

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

$ bitrix test

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

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

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

--watch [\<fileExtension>[, ...]], -w=[\<fileExtension>[, ...]]

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

$ bitrix test --watch

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

$ bitrix test -w

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

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

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

--modules \<moduleName>[, ...], -m=\<moduleName>[, ...]

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

$ bitrix test --modules main,ui,landing

--path \<path>, -p=\<path>

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

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

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

$ bitrix test -p=./main/install/js/main/loader

--extensions \<extensionName>[, ...], -e=\<extensionName>[, ...]

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

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

Создание «экстеншна»

Для создания «экстеншна»

Перейдите в директорию local/js/{module}
Выполните команду bitrix create
Ответьте на вопросы мастера

bitrix-tools / cli

readme

@bitrix/cli

Содержание

Описание

Установка

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

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

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

Сборка

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

--watch [\<fileExtension>[, ...]], -w=[\<fileExtension>[, ...]]

--test, -t

--modules \<moduleName>[, ...], -m=\<moduleName>[, ...]

--path \<path>, -p=\<path>

--extensions \<extensionName>[, ...], -e=\<extensionName>[, ...]

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

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

--watch [\<fileExtension>[, ...]], -w=[\<fileExtension>[, ...]]

--modules \<moduleName>[, ...], -m=\<moduleName>[, ...]

--path \<path>, -p=\<path>

--extensions \<extensionName>[, ...], -e=\<extensionName>[, ...]

Создание «экстеншна»