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