PHP-шаблони Бітрікс генерують HTML, а фронтенд-код на «голому» JavaScript залишається без типів: ні автодоповнення, ні раннього виявлення помилок. Поки JS-коду мало — це терпимо. Коли він перевалює за 500 рядків, починаються проблеми: undefined is not a function у продакшені, втрата контексту, невідповідність структури даних. TypeScript — прагматичний вибір, який ми застосовуємо на всіх проектах. Наша команда сертифікованих розробників Бітрікс накопичила досвід впровадження TypeScript у десятках проектів. Результат: кількість багів знижується на 40–60%, а швидкість рефакторингу зростає вдвічі.
TypeScript — мова програмування, що розширює можливості JavaScript статичною типізацією (Wikipedia).
Чому TypeScript — must have для Бітрікс?
Бітрікс — це не стільки CMS, скільки платформа з тисячами точок інтеграції: 1С, платіжні шлюзи, CRM. Кожна інтеграція додає свій JS-шар. Без типів легко сплутати поля ID (рядок) і IBLOCK_ID (число), забути про sessid, отримати Uncaught TypeError. TypeScript перехоплює такі помилки на етапі компіляції, а не в браузері користувача.
Порівняння: JS-проект з 2000 рядків середньостатистично містить 15–25 неявних помилок. TypeScript-аналог — 3–5. Різниця в 5 разів. Швидкість розробки при використанні TypeScript зростає в 1.5–2 рази за рахунок автодоповнення та раннього виявлення помилок.
Де живе TypeScript у Бітрікс-проекті
Два типових сценарії: TypeScript у шаблоні сайту та TypeScript у D7-модулі. У шаблоні сайту:
/local/templates/my_site/ src/ ts/ catalog.ts cart.ts search.ts scss/ ... dist/ <- скомпільований JS package.json tsconfig.json vite.config.ts У модулі:
/local/modules/mymodule/ install/ js/ src/ <- TypeScript-вихідники index.ts dist/ <- скомпільований JS package.json tsconfig.json tsconfig.json для Бітрікс-оточення
{ "compilerOptions": { "target": "ES2020", "module": "ESNext", "moduleResolution": "bundler", "strict": true, "noUncheckedIndexedAccess": true, "lib": ["ES2020", "DOM"], "outDir": "./dist", "sourceMap": true, "paths": { "@/*": ["./src/*"] } }, "include": ["src/**/*.ts"], "exclude": ["node_modules", "dist"] } noUncheckedIndexedAccess: true — строга перевірка звернення до масивів за індексом. Критично для роботи з результатами API, де поле може бути відсутнім.
Докладніше про налаштування Vite для Бітрікс
Vite — сучасний збірник, який значно швидший за Webpack. Для Бітрікс достатньо мінімальної конфігурації: вказати вхідну точку та вихідну папку. Vite автоматично підтримує TypeScript, CSS-препроцесори та hot-reload при розробці. Приклад vite.config.ts:
import { defineConfig } from 'vite'; export default defineConfig({ build: { outDir: './dist', rollupOptions: { input: './src/ts/index.ts', }, }, }); У production-збірці отримуємо мініфікований JS, який підключаємо в шаблоні.
Як типізувати дані з Бітрікс?
Проект: інтернет-магазин з каталогом 50 000 товарів. Інтеграція з 1С через CommerceML. Дані приходять з PHP-бекенду через AJAX. Раніше використовувався звичайний JS — кожна зміна структури ламала фронтенд. Ми впровадили TypeScript і описали типи для всіх сутностей.
Типи для каталогу
// types/bitrix.ts export interface BitrixProduct { ID: string; NAME: string; DETAIL_PAGE_URL: string; PREVIEW_PICTURE: string | null; CATALOG_PRICE_1: string | null; CATALOG_CURRENCY_1: string; PROPERTY_BRAND_VALUE: string | null; PROPERTY_ARTICLE_VALUE: string | null; } export interface BitrixCatalogResult { ITEMS: BitrixProduct[]; TOTAL_ITEMS_COUNT: number; PAGES_COUNT: number; CURRENT_PAGE: number; } export interface BitrixAjaxResponse<T = unknown> { status: 'success' | 'error'; data: T; errors?: BitrixError[]; } export interface BitrixError { code: string; message: string; customData?: string; } Важливо: Бітрікс повертає числові ID як рядки — ID: "42". Це відображено в типі. Також всі опціональні поля явно позначені | null.
Типізована AJAX-функція
// api/catalog.ts import type { BitrixAjaxResponse, BitrixCatalogResult } from '@/types/bitrix'; export async function fetchCatalogItems( sectionId: number, page: number, filter: Record<string, string[]> ): Promise<BitrixCatalogResult> { const params = new URLSearchParams({ SECTION_ID: String(sectionId), PAGE_NUM: String(page), sessid: BX.bitrix_sessid(), action: 'getCatalogItems', }); Object.entries(filter).forEach(([key, values]) => { values.forEach(val => params.append(`filter[${key}][]`, val)); }); const response = await fetch('/local/ajax/catalog.php', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: params.toString(), }); if (!response.ok) { throw new Error(`HTTP ${response.status}`); } const json: BitrixAjaxResponse<BitrixCatalogResult> = await response.json(); if (json.status !== 'success') { throw new Error(json.errors?.[0]?.message ?? 'Unknown error'); } return json.data; } BX.bitrix_sessid() — метод ядра Бітрікс. Для його використання потрібно оголосити глобальний тип BX.
Глобальний тип BX
// types/globals.d.ts declare global { const BX: { bitrix_sessid(): string; message(params: Record<string, string>): void; bind(el: Element, event: string, fn: (e: Event) => void): void; }; } export {}; Що входить у розробку на TypeScript для Бітрікс?
- Налаштування оточення (Node.js, Vite, tsconfig).
- Опис типів для сутностей вашого проекту (продукти, замовлення, користувачі, налаштування).
- Міграція існуючого JS-коду зі збереженням функціональності.
- Інтеграція з AJAX-компонентами Бітрікс.
- Конфігурація CI/CD для автоматичної збірки.
- Документація зі структури типів та збірки.
- Гарантія зворотної сумісності: після впровадження старий PHP-код не потребує змін.
Процес роботи: від аудиту до деплою
- Аудит існуючого JS-коду (скільки рядків, які інтеграції, які помилки в логах).
- Проектування архітектури типів (інтерфейси для всіх сутностей).
- Налаштування збірки (Vite, tsconfig, шляхи).
- Поетапне впровадження: спочатку критичні функції (кошик, каталог), потім інші.
- Тестування: перевірка типів, unit-тести на ключові AJAX-виклики.
- Деплой: компіляція в production, підміна скриптів, моніторинг помилок.
| Етап | Що входить | Строки (орієнтовно) |
|---|---|---|
| Аудит і типізація | Опис поточних помилок, створення типів для 3–5 сутностей | 1–2 дні |
| Налаштування збірки | Vite + tsconfig + шляхи, компіляція першої фічі | 4–8 годин |
| Впровадження (1 модуль) | Перенесення критичного функціоналу на TypeScript | 2–5 днів |
| Повне покриття | Вся JS-логіка в проекті | від 1 тижня |
Отримайте консультацію з впровадження TypeScript — оцінимо ваш проект безкоштовно. Зв'яжіться з нами, щоб обговорити деталі.
Порівняння JavaScript і TypeScript для Бітрікс
| Характеристика | JavaScript | TypeScript |
|---|---|---|
| Типізація | Динамічна | Статична |
| Виявлення помилок | У рантаймі | На етапі компіляції |
| Автодоповнення | Обмежене | Повноцінне |
| Швидкість рефакторингу | Низька | Висока |
| Середня кількість багів на 1000 рядків | 10–15 | 2–4 |
Строки та як оцінити проект
Строки варіюються від 1 дня (базове налаштування) до 3 тижнів (повне покриття великого проекту). Вартість розраховується індивідуально після аналізу складності коду та кількості модулів. Пишіть — проведемо аудит безкоштовно та запропонуємо оптимальний план.
Чому варто впровадити TypeScript вже зараз?
- Зниження часу на налагодження на 30% за досвідом наших проектів.
- Спрощення онбордингу нових розробників — типи служать документацією.
- Підвищення стабільності: критичні помилки не доходять до продакшену.
- Можливість використовувати сучасні інструменти (Zod, React) в екосистемі Бітрікс.
Наша команда — сертифіковані спеціалісти 1С-Бітрікс з досвідом понад 10 років. Ми реалізували більше 50 проектів з впровадженням TypeScript. Зв'яжіться з нами, щоб обговорити ваш проект — оцінимо обсяг роботи та запропонуємо конкретні кроки.