Налаштування 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 години безкоштовно. Зв'яжіться з нами для консультації — обговоримо архітектуру, терміни та вартість індивідуально. Замовте налаштування прямо зараз.