Chef

CLI-инструмент для сборки, тестирования и поддержки JS-расширений Bitrix

English

Возможности

• 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 для раздельного запуска)
chef stat	Анализ размера бандлов и зависимостей
chef create <name>	Создание нового расширения
chef init	Инициализация окружения сборки и тестов
chef init build	Инициализация TypeScript, алиасов и browserslist
chef init tests	Инициализация только тестового окружения
chef flow-to-ts	Миграция Flow.js в TypeScript

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

Создайте bundle.config.ts в директории расширения:

export default {
  input: './src/my.extension.ts',
  output: {
    js: './dist/my.extension.bundle.js',
    css: './dist/my.extension.bundle.css',
  },
  namespace: 'BX.MyExtension',
};

Параметры

Параметр	Тип	Описание
input	string	Точка входа
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)
rebuild	string[]	Расширения для пересборки после сборки текущего

Также поддерживается JavaScript-конфигурация (bundle.config.js).

Проектный конфиг

Файл chef.config.ts в корне проекта задаёт правила для всех расширений:

export default {
  deny: {
    sfc: true,                         // запретить Vue SFC
    standalone: {
      severity: 'warning',             // или предупреждать
      message: 'Standalone не рекомендуется',
    },
  },
  defaults: { targets: 'last 2 versions' },
  enforce: { sourceMaps: false },
};

• deny — запрет опций (error блокирует сборку, warning показывает предупреждение)
• defaults — значения по умолчанию (можно переопределить в bundle.config)
• enforce — принудительные значения (нельзя переопределить)

Browserslist

Chef использует browserslist для определения целевых браузеров при транспиляции через Babel и автопрефиксинге CSS.

По умолчанию Chef нацеливается на baseline widely available — браузеры с широкой поддержкой современных веб-возможностей.

Как это работает

1. Если targets указан в bundle.config.ts — используется он
2. Иначе Chef ищет файл .browserslistrc вверх по дереву директорий
3. Если файл не найден — используется baseline widely available

Кастомные цели

Указать цели напрямую в конфиге:

export default {
  // ...
  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.css   # Скомпилированные стили
└── test/
    ├── unit/                  # Unit-тесты (Mocha + Chai)
    │   └── example.test.ts
    └── e2e/                   # E2E-тесты (Playwright)
        └── example.spec.ts

Конфигурация TypeScript (tsconfig.json) размещается в корне проекта и используется всеми расширениями. Создаётся командой chef init build.

Также поддерживаются JavaScript-расширения (точки входа .js).

Настройка TypeScript

Инициализация окружения сборки:

chef init build

Команда:

1. Сканирует все расширения в проекте
2. Генерирует aliases.tsconfig.json с алиасами путей для каждого расширения
3. Создаёт tsconfig.json с рекомендованными настройками
4. Создаёт .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	Учётные данные для автоматической аутентификации при тестировании

Настройка .env.test

Заполните учётные данные вашей локальной установки Bitrix:

BASE_URL=http://localhost
LOGIN=admin
PASSWORD=your_password

Безопасность: Не коммитьте .env.test в систему контроля версий — файл содержит конфиденциальные данные.

Установка браузеров Playwright

npx playwright install

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

chef test main.core                       # Тестирование конкретного расширения
chef test ui.* --headed                   # Запуск с видимым браузером
chef test main.core -w                    # Watch-режим
chef test --grep "should render"          # Фильтр по имени теста
chef test main.core --debug               # Открыть браузер с DevTools и sourcemaps
chef test main.core --project chromium    # Запуск только в конкретном браузере

Требования

• Node.js >= 22
• Проект на Bitrix или директория с исходниками модуля

Лицензия

MIT

---

Создано для разработчиков Bitrix