Сборка ассетов Vite и Webpack в проекте на Битрикс

1С-Битрикс не требует сборщика: положил CSS в template_styles.css, и он подключился. Но как только в проекте появляются препроцессоры, модульный JavaScript или npm-пакеты, встаёт вопрос сборки — а вместе с ним и вопрос, как подружить современный фронтенд-инструментарий с PHP-шаблоном.

Разберём, когда сборщик действительно нужен, как устроить структуру папок в шаблоне, как подключать собранные файлы с учётом хешей в именах и что делать с режимом разработки, когда бэкенд — обычный PHP, а не Node.

Нужен ли сборщик

Честный ответ — не всегда. Ориентир такой:

Последний пункт стоит обдумать заранее. Если предполагается, что кто-то будет править стили через административный интерфейс, сборка это сломает: файл перезапишется при следующем запуске.

Структура папок

Рабочая раскладка внутри шаблона — исходники отдельно, результат отдельно:

/local/templates/main/
    header.php
    footer.php
    template_styles.css      <- только критические стили, вручную
    /src/                    <- исходники, в сборку
        main.js
        /styles/
            main.scss
            /blocks/
        /components/
    /assets/                 <- результат сборки
        /js/
        /css/
    package.json
    vite.config.js

Ключевое решение: папка /src/ не должна попадать в отдачу веб-сервером. Она нужна только на этапе разработки. То же касается node_modules — эту папку обязательно исключают из выгрузки на боевой сервер.

Настройка Vite

Vite ориентирован на одностраничные приложения, но для классического сайта его настраивают в режиме сборки библиотеки — без своего index.html и без подмены бэкенда.

// vite.config.js
import { defineConfig } from 'vite';

export default defineConfig({
    base: '/local/templates/main/assets/',

    build: {
        outDir: 'assets',
        emptyOutDir: true,
        manifest: true,

        rollupOptions: {
            input: {
                main: 'src/main.js',
            },
            output: {
                entryFileNames: 'js/[name].[hash].js',
                chunkFileNames: 'js/[name].[hash].js',
                assetFileNames: 'css/[name].[hash][extname]',
            },
        },
    },
});

Разберём важные параметры:

Подключение собранных файлов

Хеш в имени файла меняется при каждой сборке, поэтому жёстко прописать путь в header.php нельзя. Имя берут из манифеста — небольшого JSON, который Vite кладёт рядом со сборкой.

Простой хелпер, который читает манифест и подключает файлы через API Битрикс:

<?php // /local/php_interface/assets.php

function includeBuiltAssets(string $entry = 'src/main.js'): void
{
    global $APPLICATION;

    $tplPath  = SITE_TEMPLATE_PATH . '/assets';
    $manifest = $_SERVER['DOCUMENT_ROOT'] . $tplPath . '/.vite/manifest.json';

    // в старых версиях Vite манифест лежит на уровень выше
    if (!file_exists($manifest)) {
        $manifest = $_SERVER['DOCUMENT_ROOT'] . $tplPath . '/manifest.json';
    }

    if (!file_exists($manifest)) {
        return;
    }

    $data = json_decode(file_get_contents($manifest), true);

    if (empty($data[$entry])) {
        return;
    }

    $item = $data[$entry];

    // стили, которые Vite вынес из этой точки входа
    foreach (($item['css'] ?? []) as $css) {
        $APPLICATION->SetAdditionalCSS($tplPath . '/' . $css);
    }

    // сам скрипт
    if (!empty($item['file'])) {
        $APPLICATION->AddHeadScript($tplPath . '/' . $item['file']);
    }
}

Подключаем хелпер и вызываем его в шаблоне:

<?php // /local/php_interface/init.php
require_once __DIR__ . '/assets.php';

<?php // header.php, до вызова ShowHead()
includeBuiltAssets();
?>
<?$APPLICATION->ShowHead()?>

Обратите внимание на порядок: подключение должно идти до ShowHead(), иначе стили и скрипты просто некуда будет вывести. Подробнее о методах подключения — в статье Подключение CSS и JS в Битрикс.

Режим разработки

Здесь кроется главное отличие от привычного фронтенд-проекта. Vite поднимает свой dev-сервер и раздаёт модули с горячей перезагрузкой, но страницы сайта отдаёт PHP. Схема с полноценным HMR требует, чтобы шаблон в режиме разработки подключал скрипты не из /assets/, а с адреса dev-сервера.

Настраивается это несложно, но добавляет в проект зависимость от запущенного Node. Практичная альтернатива для типового сайта на Битрикс — режим наблюдения:

{
  "scripts": {
    "dev":   "vite build --watch",
    "build": "vite build"
  }
}

Сборщик пересобирает файлы при каждом изменении исходников, а страницу вы обновляете сами. Горячей замены модулей нет, зато никакой дополнительной настройки и никаких расхождений между разработкой и боевым режимом.

Webpack как альтернатива

Webpack решает ту же задачу и подходит там, где проект уже на нём или нужна специфичная сборка. Принцип подключения не меняется: включаете плагин манифеста, а PHP читает получившийся JSON тем же способом.

Для нового проекта на Битрикс Vite обычно удобнее: конфигурация короче, сборка быстрее, а всё, что нужно от инструмента, — собрать CSS и JS в папку.

Сборка и объединение файлов Битрикс

В настройках главного модуля есть объединение CSS и JS. Если файлы уже собраны сборщиком в один бандл, дополнительное объединение ничего не даст, а отладку усложнит: к имени добавляется ещё один слой склейки.

Разумный вариант — оставить объединение включённым для стилей компонентов и служебных скриптов ядра, но понимать, что собранный бандл в нём тоже участвует. Если после включения оптимизации что-то сломалось, проверку начинайте с отключения объединения.

Что коммитить в репозиторий

Вопрос спорный, и ответ зависит от того, как устроен деплой:

• Есть сборка на сервере или в CI — папку /assets/ добавляют в .gitignore, в репозитории только исходники.
• Деплой копированием файлов по FTP — собранные файлы приходится коммитить, иначе на боевом сервере их просто не окажется.

Что исключают всегда:

# .gitignore
node_modules/
.vite/
*.log

Частые ошибки

• Не задан base. Пути к шрифтам и картинкам внутри собранного CSS указывают в корень сайта, и ресурсы не находятся.
• Файлы подключены после ShowHead(). Вызовы SetAdditionalCSS отрабатывают, но выводить их уже поздно.
• Хеш в имени без чтения манифеста. Путь прописан жёстко, после первой же пересборки страница остаётся без стилей.
• Папка node_modules выложена на боевой сервер. Десятки тысяч файлов, замедление бэкапов и потенциальная дыра в безопасности.
• Исходники /src/ доступны по прямой ссылке. Не критично, но отдавать наружу их незачем.
• Сборка настроена, а контент-менеджер правит стили через админку. Правки исчезают при следующей сборке, и никто не понимает почему.

Итог

Сборщик в проекте на 1С-Битрикс оправдан тогда, когда появились препроцессоры, модульный JavaScript или npm-пакеты. Для сайта с парой сотен строк CSS штатного template_styles.css достаточно.

Схема интеграции одинакова для Vite и Webpack: исходники в /src/, результат в /assets/, хеши в именах файлов для обхода браузерного кеша и небольшой PHP-хелпер, который читает манифест и подключает файлы штатными методами до вызова ShowHead().

Похожие статьи

Спрайты и иконки в шаблоне БитриксАдаптивность и мобильная версия на БитриксСвой шаблон для конкретного раздела сайта в БитриксВключаемые области в Битрикс