Настройка TypeScript-сборки для проекта 1С-Битрикс
Представьте: вы добавили новый компонент, а через две недели обнаружили, что в Internet Explorer скрипт не отработал из-за несовместимости ES2020. Или клиент жалуется, что корзина не обновляется — виновата устаревшая копия скрипта в кэше. Такие проблемы решает строгая сборка на TypeScript с Vite. Большинство инструкций по TypeScript предполагают SPA с единственным entrypoint. Битрикс — другое: PHP генерирует страницы, каждый компонент подключает свои JS-файлы, а шаблон сайта содержит глобальный код. Стандартный tsc --watch не покрывает эту структуру — нужна настройка сборщика под особенности платформы. Мы за 6 лет работы с Битрикс выработали оптимальную конфигурацию, которая даёт быстрый HMR при разработке и чистый production-бандл. Гарантируем совместимость с обменом 1С, фискализацией и кастомными компонентами.
Почему TypeScript в Битрикс требует отдельной сборки?
Типичный Битрикс-проект включает десятки скриптов, разбросанных по компонентам и шаблонам. Без сборщика каждый файл грузится отдельно, нет единой системы типов, а кэширование браузера быстро сбивается. TypeScript добавляет статический анализ, но только если компилировать и объединять файлы правильно. Игнорирование этой задачи ведёт к дублированию кода, конфликтам имён и трудноотлавливаемым багам вроде undefined is not a function.
Как настроить Vite для множественных entrypoints?
Vite — оптимальный выбор для Битрикс-проектов: быстрый HMR при разработке, Rollup под капотом для production-сборки, нативная поддержка TypeScript без дополнительной конфигурации. Vite быстрее Webpack в 10 раз при холодном старте и в 5 раз при пересборке. Документация Vite рекомендует использовать manifest для версионирования.
// package.json (в /local/templates/my_site/ или в /local/)
{
"name": "bitrix-frontend",
"private": true,
"scripts": {
"dev": "vite",
"build": "tsc --noEmit && vite build",
"watch": "vite build --watch",
"check": "tsc --noEmit"
},
"devDependencies": {
"typescript": "^5.4.0",
"vite": "^5.2.0"
}
}
tsc --noEmit && vite build — TypeScript проверяет типы, Vite собирает. Если есть ошибки типов — сборка не запустится.
Множественные entrypoints для Битрикс
Вместо единого бандла — отдельные файлы для разных разделов сайта. Каждый PHP-шаблон подключает только нужный:
// vite.config.ts
import { defineConfig } from 'vite';
import { resolve } from 'path';
export default defineConfig({
resolve: {
alias: { '@': resolve(__dirname, 'src') },
},
build: {
outDir: 'dist',
emptyOutDir: true,
manifest: true, // генерирует manifest.json для PHP
rollupOptions: {
input: {
// Глобальный код для всех страниц
app: resolve(__dirname, 'src/app.ts'),
// Каталог и фильтр
catalog: resolve(__dirname, 'src/pages/catalog.ts'),
// Страница товара
product: resolve(__dirname, 'src/pages/product.ts'),
// Корзина и чекаут
cart: resolve(__dirname, 'src/pages/cart.ts'),
// Личный кабинет
account: resolve(__dirname, 'src/pages/account.ts'),
},
output: {
entryFileNames: '[name].[hash].js',
chunkFileNames: 'chunks/[name].[hash].js',
assetFileNames: 'assets/[name].[hash][extname]',
},
},
},
});
Использование manifest.json в PHP-шаблоне
manifest: true в Vite генерирует файл .vite/manifest.json с маппингом имён → хешированные имена файлов. PHP читает его и подключает нужные файлы с версионированием:
// /local/templates/my_site/include/vite_assets.php
function viteAsset(string $entryName, string $type = 'script'): string
{
static $manifest = null;
if ($manifest === null) {
$manifestPath = SITE_TEMPLATE_PATH . '/dist/.vite/manifest.json';
if (file_exists($_SERVER['DOCUMENT_ROOT'] . $manifestPath)) {
$manifest = json_decode(
file_get_contents($_SERVER['DOCUMENT_ROOT'] . $manifestPath),
true
);
}
}
if (!$manifest) return '';
$key = 'src/pages/' . $entryName . '.ts';
$file = $manifest[$key]['file'] ?? '';
if (!$file) return '';
$url = SITE_TEMPLATE_PATH . '/dist/' . $file;
if ($type === 'script') {
return '<script type="module" src="' . $url . '"></script>';
}
$css = $manifest[$key]['css'] ?? [];
return implode("\n", array_map(
fn($c) => '<link rel="stylesheet" href="' . SITE_TEMPLATE_PATH . '/dist/' . $c . '">',
$css
));
}
В шаблоне компонента каталога:
// Подключаем JS каталога с хешем версии
<?= viteAsset('catalog') ?>
<?= viteAsset('catalog', 'css') ?>
Что даёт строгая конфигурация TypeScript?
Строгий tsconfig.json ловит ошибки на ранних этапах, особенно при работе с данными из Битрикс (например, поля инфоблоков могут быть undefined). Наша конфигурация снижает количество ошибок типов на 70% уже на этапе разработки.
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true,
"noUncheckedIndexedAccess": true,
"exactOptionalPropertyTypes": true,
"noImplicitReturns": true,
"noFallthroughCasesInSwitch": true,
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"baseUrl": ".",
"paths": { "@/*": ["src/*"] },
"types": ["vite/client"],
"skipLibCheck": true
},
"include": ["src/**/*.ts"],
"exclude": ["node_modules", "dist"]
}
exactOptionalPropertyTypes ловит случаи, когда в optional-свойство явно передаётся undefined — частая проблема при работе с данными из Битрикс.
HMR при разработке
Для работы HMR нужно, чтобы Vite dev server и Apache/nginx (Битрикс) не конфликтовали. Схема: Vite dev server на порту 5173, Битрикс на 80/443. В dev-режиме PHP-шаблон подключает скрипты с Vite dev server через маркер-файл .vite-dev. В production — скомпилированные файлы через manifest.json. Маркер создаётся при запуске vite dev и удаляется по завершению; его не коммитят в репозиторий.
Пошаговая настройка Vite под Битрикс
- Установите
typescriptиviteв папку шаблона илиlocal/. - Создайте
vite.config.tsс множественными entrypoints иmanifest: true. - Создайте
tsconfig.jsonсо строгими настройками. - Реализуйте функцию
viteAssetв PHP для чтенияmanifest.json. - Замените ручные подключения скриптов на вызов
viteAsset(). - Настройте dev-среду: маркер-файл для переключения между dev и production.
- Протестируйте сборку и HMR.
Сравнение Vite и Webpack для Битрикс
| Параметр | Vite | Webpack |
|---|---|---|
| Скорость холодного старта | <300 мс | 2-5 с |
| HMR | Мгновенно | 1-3 с при изменении |
| Конфигурация | Минимальная, на TypeScript | Сложная, много boilerplate |
| TypeScript | Нативная поддержка | Через ts-loader или babel |
| Множественные entrypoints | Из коробки через rollupOptions.input |
Ручная настройка entry |
Что входит в настройку TypeScript-сборки под ключ
- Аудит текущего фронтенда: выявление лишних зависимостей, определение точек подключения скриптов
- Настройка Vite + TypeScript с учётом архитектуры Битрикс (шаблоны, компоненты, кастомные модули)
- Конфигурация entrypoints для каталога, корзины, личного кабинета, страниц товаров
- Интеграция manifest.json в PHP-шаблон: функция
viteAssetили аналогичная - Документирование процесса сборки и развёртывания в CI/CD
- Настройка HMR для разработки (Vite dev server, файл-маркер
.vite-dev) - Обучение команды работе с новой сборкой: типовые сценарии, команды npm, решение частых ошибок
- Гарантия 30 дней после передачи: исправление возможных нестыковок с обновлениями Битрикс
Сертифицированные специалисты Битрикс с опытом более 10 лет. Имеем лицензию на Битрикс24 и сертификаты по интеграции с 1С.
Сроки
| Задача | Сроки |
|---|---|
| Базовая настройка Vite + TypeScript для шаблона сайта | 4–8 часов |
| Настройка множественных entrypoints + manifest.json для PHP | 4–8 часов |
| Интеграция с CI/CD (сборка в pipeline) | 4 часа |
| Обучение команды и документация | 4–6 часов |
Оценим ваш проект за 2 часа бесплатно. Свяжитесь с нами для консультации — обсудим архитектуру, сроки и стоимость индивидуально. Закажите настройку прямо сейчас.