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. Свяжитесь с нами, чтобы обсудить ваш проект — оценим объём работы и предложим конкретные шаги.