CLI-инструмент для сборки, тестирования и поддержки JS-расширений Bitrix
- TypeScript First — нативная поддержка TypeScript с автоматической транспиляцией
- Сборка — бандлер на основе Rollup с Babel, PostCSS и автозаменой
process.env.NODE_ENV - Тесты — unit-тесты (Mocha + Chai) в реальных браузерах через Playwright и E2E-тесты
- Линтинг — интеграция с ESLint
- Scaffold — создание новых расширений командой
chef create - Миграция — конвертация Flow.js в TypeScript командой
chef flow-to-ts - Диагностика — анализ зависимостей, размеров бандлов, циклических зависимостей и неиспользуемых расширений
npm install -g @bitrix/chefИнициализация окружения сборки:
chef init buildСоздание и сборка первого расширения:
chef create my.extension
chef build my.extension| Команда | Описание |
|---|---|
chef build | Сборка расширений (TypeScript, Babel, PostCSS) |
chef test | Запуск unit и E2E тестов (подкоманды unit/e2e/module для раздельного запуска) |
chef typecheck | Проверка типов TypeScript в расширениях |
chef lint | Линтинг расширений через ESLint |
chef diag | Диагностика: зависимости, размеры бандлов, циклы, неиспользуемые расширения |
chef baseline | Проверка доступности веб-фич для текущих browser targets |
chef create <name> | Создание нового расширения |
chef aliases | Регенерация алиасов путей для TypeScript |
chef init build | Инициализация TypeScript, алиасов и browserslist |
chef init tests | Инициализация тестового окружения |
chef init hooks | Установка VCS-хуков для автообновления алиасов |
chef flow-to-ts | Миграция Flow.js в TypeScript |
Создайте bundle.config.ts в директории расширения:
exportdefault{input: './src/my.extension.ts',output: {js: './dist/my.extension.bundle.js',css: './dist/my.extension.bundle.css',},namespace: 'BX.MyExtension',};| Параметр | Тип | Описание |
|---|---|---|
input | string | Точка входа (.ts, .js или .css) |
output | string | {js?, css?} | Путь к выходному бандлу |
namespace | string | Глобальный неймспейс для экспортов |
concat | {js?: string[], css?: string[]} | Конкатенация файлов в указанном порядке |
targets | string | string[] | Целевые браузеры для транспиляции |
sourceMaps | boolean | Генерация source maps |
minification | boolean | object | Минификация через Terser |
treeshake | boolean | Удаление неиспользуемого кода (по умолчанию: true) |
plugins | Plugin[] | Кастомные Rollup-плагины |
resolveNodeModules | boolean | Резолв зависимостей из node_modules |
babel | boolean | Включение/отключение Babel (по умолчанию: true) |
transformClasses | boolean | string[] | Транспиляция классов — все (true) или по именам |
rebuild | string[] | Расширения для пересборки после сборки текущего |
emitDeclaration | boolean | Генерация .d.ts с namespace-декларациями (по умолчанию: true) |
safeNamespaces | boolean | Безопасные обращения к неймспейсам зависимостей через optional chaining |
standalone | boolean | object | Автономная сборка с инлайном зависимостей |
cssImages | object | Обработка изображений в CSS (type, maxSize, absolutePaths) |
baseline | boolean | Проверка доступности веб-фич при сборке (по умолчанию: true) |
Также поддерживается JavaScript-конфигурация (
bundle.config.js).
Файл chef.config.ts в корне проекта задаёт правила для всех расширений:
exportdefault{deny: {sfc: true,// запретить Vue SFCexportDefault: true,// запретить export defaultstandalone: {severity: 'warning',// или предупреждатьmessage: 'Standalone не рекомендуется',},},defaults: {targets: 'last 2 versions'},enforce: {sourceMaps: false},};- deny — запрет опций (
errorблокирует сборку,warningпоказывает предупреждение) - defaults — значения по умолчанию (можно переопределить в
bundle.config) - enforce — принудительные значения (нельзя переопределить)
Chef использует browserslist для определения целевых браузеров при транспиляции через Babel и автопрефиксинге CSS.
По умолчанию Chef нацеливается на baseline widely available — браузеры с широкой поддержкой современных веб-возможностей.
- Если
targetsуказан вbundle.config.ts— используется он - Иначе Chef ищет файл
.browserslistrcвверх по дереву директорий - Если файл не найден — используется
baseline widely available
Указать цели напрямую в конфиге:
exportdefault{// ...targets: ['last 2 versions','not dead'],};Или создать файл .browserslistrc в корне проекта (команда chef init build создаст его автоматически):
baseline widely available
local/js/vendor/extension/
├── bundle.config.ts # Конфигурация сборки
├── config.php # Конфиг расширения Bitrix
├── src/
│ └── extension.ts # Точка входа (имя совпадает с расширением)
├── dist/
│ ├── extension.bundle.js # Скомпилированный бандл
│ ├── extension.bundle.d.ts # Декларации типов (TypeScript)
│ └── extension.bundle.css # Скомпилированные стили
└── test/
├── unit/ # Unit-тесты (Mocha + Chai)
│ └── example.test.ts
└── e2e/ # E2E-тесты (Playwright)
└── example.spec.ts
Конфигурация TypeScript (tsconfig.json) размещается в корне проекта и используется всеми расширениями. Создаётся командой chef init build.
Также поддерживаются JavaScript-расширения (точки входа
.js).
Инициализация окружения сборки:
chef init buildКоманда:
- Сканирует все расширения в проекте
- Генерирует
aliases.tsconfig.jsonс алиасами путей для каждого расширения - Создаёт
tsconfig.jsonс рекомендованными настройками - Создаёт
.browserslistrcс рекомендованными целевыми браузерами
После инициализации можно импортировать расширения по имени:
import{Loc,Tag}from'main.core';import{Button}from'ui.buttons';Если
tsconfig.jsonуже существует, команда предложит перезаписать его. Можно вручную добавить"extends": "./aliases.tsconfig.json"в существующий конфиг.
Для запуска unit и E2E тестов необходимо сначала инициализировать тестовое окружение:
chef init testsСоздаёт два файла в корне проекта:
| Файл | Описание |
|---|---|
playwright.config.ts | Конфиг Playwright для запуска unit и E2E тестов в браузере |
.env.test | Учётные данные для автоматической аутентификации при тестировании |
Заполните учётные данные вашей локальной установки Bitrix:
BASE_URL=http://localhostLOGIN=adminPASSWORD=your_passwordБезопасность: Не коммитьте
.env.testв систему контроля версий — файл содержит конфиденциальные данные.
npx playwright installchef test main.core # Тестирование конкретного расширения
chef test ui.* --headed # Прямые дочерние, с видимым браузером
chef test im.v2.**# Все вложенные расширения
chef test main.core -w # Watch-режим
chef test --grep "should render"# Фильтр по имени теста
chef test main.core --debug # Открыть браузер с DevTools и sourcemaps
chef test main.core --project chromium # Запуск только в конкретном браузере
chef test module crm # Сценарные тесты модуля (несколько расширений)
chef test e2e ui.buttons --update-snapshots # Опции Playwright уходят раннеру как есть- Node.js >= 22
- Проект на Bitrix или директория с исходниками модуля
Создано для разработчиков Bitrix