254  /  382
Справочник

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

Просмотров: 54810
Дата последнего изменения: 29.02.2024
Анна Кокина
Сложность урока:
4 уровень - сложно, требуется сосредоточиться, внимание деталям и точному следованию инструкции.
1
2
3
4
5
Недоступно в лицензиях:
Ограничений нет

Описание

@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 [<fileExtension>[, ...]], -w=[<fileExtension>[, ...]]

    Режим отслеживания изменений. Пересобирает бандлы Бандл (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 <moduleName>[, ...], -m=<moduleName>[, ...]

    Сборка только указанных модулей. Параметр поддерживается только в корневой директории c модулями 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
    

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

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

$ bitrix test

Примечание: Тестами считаются 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} {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");.

  Видео от разработчика



16
Курсы разработаны в компании «1С-Битрикс»

Если вы нашли неточность в тексте, непонятное объяснение, пожалуйста, сообщите нам об этом в комментариях.
Развернуть комментарии