Настройка TypeScript-сборки для проекта 1С-Битрикс

Настройка 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 под Битрикс

1. Установите typescript и vite в папку шаблона или local/.
2. Создайте vite.config.ts с множественными entrypoints и manifest: true.
3. Создайте tsconfig.json со строгими настройками.
4. Реализуйте функцию viteAsset в PHP для чтения manifest.json.
5. Замените ручные подключения скриптов на вызов viteAsset().
6. Настройте dev-среду: маркер-файл для переключения между dev и production.
7. Протестируйте сборку и HMR.

Сравнение Vite и Webpack для Битрикс

Что входит в настройку TypeScript-сборки под ключ

• Аудит текущего фронтенда: выявление лишних зависимостей, определение точек подключения скриптов
• Настройка Vite + TypeScript с учётом архитектуры Битрикс (шаблоны, компоненты, кастомные модули)
• Конфигурация entrypoints для каталога, корзины, личного кабинета, страниц товаров
• Интеграция manifest.json в PHP-шаблон: функция viteAsset или аналогичная
• Документирование процесса сборки и развёртывания в CI/CD
• Настройка HMR для разработки (Vite dev server, файл-маркер .vite-dev)
• Обучение команды работе с новой сборкой: типовые сценарии, команды npm, решение частых ошибок
• Гарантия 30 дней после передачи: исправление возможных нестыковок с обновлениями Битрикс

Сертифицированные специалисты Битрикс с опытом более 10 лет. Имеем лицензию на Битрикс24 и сертификаты по интеграции с 1С.

Сроки

Оценим ваш проект за 2 часа бесплатно. Свяжитесь с нами для консультации — обсудим архитектуру, сроки и стоимость индивидуально. Закажите настройку прямо сейчас.