Возможности

• 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 | Минификация через OXC | | treeshake | boolean | Удаление неиспользуемого кода (по умолчанию: true) | | plugins | Plugin[] | Кастомные Rollup-плагины | | resolveNodeModules | boolean | Резолв зависимостей из node_modules | | babel | boolean | Включение/отключение Babel (по умолчанию: true) | | rebuild | string[] | Расширения для пересборки после сборки текущего | | emitDeclaration | boolean | Генерация .d.ts с namespace-декларациями (по умолчанию: true) |

Также поддерживается 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.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).

Настройка 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 build 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    # Запуск только в конкретном браузере

Требования

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

Лицензия

MIT