TypeScript для 1С-Бітрікс: розробка з типізацією

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, де поле може бути відсутнім.

import { defineConfig } from 'vite';

export default defineConfig({
    build: {
        outDir: './dist',
        rollupOptions: {
            input: './src/ts/index.ts',
        },
    },
});

Як типізувати дані з Бітрікс?

Проект: інтернет-магазин з каталогом 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-код не потребує змін.

Процес роботи: від аудиту до деплою

1. Аудит існуючого JS-коду (скільки рядків, які інтеграції, які помилки в логах).
2. Проектування архітектури типів (інтерфейси для всіх сутностей).
3. Налаштування збірки (Vite, tsconfig, шляхи).
4. Поетапне впровадження: спочатку критичні функції (кошик, каталог), потім інші.
5. Тестування: перевірка типів, unit-тести на ключові AJAX-виклики.
6. Деплой: компіляція в production, підміна скриптів, моніторинг помилок.

Отримайте консультацію з впровадження TypeScript — оцінимо ваш проект безкоштовно. Зв'яжіться з нами, щоб обговорити деталі.

Порівняння JavaScript і TypeScript для Бітрікс

Строки та як оцінити проект

Строки варіюються від 1 дня (базове налаштування) до 3 тижнів (повне покриття великого проекту). Вартість розраховується індивідуально після аналізу складності коду та кількості модулів. Пишіть — проведемо аудит безкоштовно та запропонуємо оптимальний план.

Чому варто впровадити TypeScript вже зараз?

• Зниження часу на налагодження на 30% за досвідом наших проектів.
• Спрощення онбордингу нових розробників — типи служать документацією.
• Підвищення стабільності: критичні помилки не доходять до продакшену.
• Можливість використовувати сучасні інструменти (Zod, React) в екосистемі Бітрікс.

Наша команда — сертифіковані спеціалісти 1С-Бітрікс з досвідом понад 10 років. Ми реалізували більше 50 проектів з впровадженням TypeScript. Зв'яжіться з нами, щоб обговорити ваш проект — оцінимо обсяг роботи та запропонуємо конкретні кроки.

Чому верстка сайтів на 1С-Бітрікс вимагає професіоналізму?

Відкриваєте template.php у попереднього підрядника — а там SQL-запити, бізнес-логіка та inline-стилі в одному файлі. На кожному другому проєкті, який ми беремо на підтримку, код шаблонів виглядає як звалище: кеш не працює, додати нову фічу — переписуй все. Виправлення такої верстки може коштувати чимало, а втрачений виторг через зламаний кошик у пік сезону може сягати десятків тисяч гривень.

Ми — команда сертифікованих розробників 1С-Бітрікс із десятирічним досвідом. За нашими плечима понад 50 успішних проектів верстки та підтримки. Наш підхід строго розділяє: логіка — в result_modifier.php або component_epilog.php, представлення — в template.php. Жодного CIBlockElement::GetList в шаблоні. Це скорочує час правок на 30–40% та виключає типові помилки, які ламають кеш. Подібну проблему виправляли клієнту з інтернет-магазину — він місяць не міг оновити блок «Акції». Після налаштування тегованого кеша правки вставали за хвилину, а не за день.

Отримайте безкоштовний аудит вашого проекту — зв'яжіться з нами.

Як правильно організувати шаблони компонентів?

Кастомний шаблон — це не один файл, а структура з п’яти-шести файлів:

• template.php — тільки HTML та виведення $arResult
• result_modifier.php — підготовка даних, додаткові вибірки
• component_epilog.php — код після кешування (лічильники, динаміка)
• style.css та script.js — підключаються через Asset::getInstance()->addCss() та addJs() (не через <link> — інакше ламається об'єднання)
• .parameters.php — параметри візуального редактора

Приклад структури для каталогу:

local/templates/your_template/components/bitrix/catalog.section/.default/
├── template.php
├── result_modifier.php
├── component_epilog.php
├── style.css
├── script.js
└── .parameters.php

Типові шаблони, які верстаємо під ключ:

Кешування: чому воно ламається і як лагодимо?

Компонентне кешування в Бітрікс ламається однією помилкою: вивели ім'я користувача всередині кешованого каталогу — всі бачать одне ім'я. Рішення — component_epilog.php для динамічних вставок.

Tagged cache ($this->setResultCacheKeys, CIBlock::clearIblockTagCache) налаштовуємо обов'язково. Змінили товар — очищується кеш лише цього товару, а не всього розділу. На проєкті з 50 000 товарів це дає приріст швидкості на 40% — в 1.4 раза швидше порівняно з повним скиданням.

Реальний кейс. Наш клієнт скаржився — на сторінці каталогу у всіх один кошик. Виявилося, попередній розробник вивів $_SESSION['BASKET'] всередині template.php компонента catalog.section. Компонент кешувався на годину — кошик застиг. Перенесли виведення в component_epilog.php, налаштували тегований кеш на sale.basket.basket.line. Сторінка не втратила у швидкості, кошик став актуальним. Збитки від несправного кошика в пік сезону могли бути значними, а вартість виправлення — помірною.

CSS-підходи: BEM, Tailwind або гібрид?

Для великих проєктів (30+ шаблонів) використовуємо BEM — .product-card__price, .product-card--featured. Стилі ізольовані, конфліктів немає. У Бітрікс обгортки з класами bx-component не чіпаємо — обгортаємо свій BEM-блок всередині.

Для типових завдань (лендінги, адмінки) беремо Tailwind 3+ з PurgeCSS — підсумковий CSS 10–30 КБ замість сотень. Дизайн-токени в tailwind.config.js фіксують кольори, шрифти, відступи в одному місці.

На більшості проєктів застосовуємо гібрид: BEM для структурних компонентів (каталог, картка, чекаут), Tailwind для утилітарних речей (відступи, flex-розкладки). Межу обговорюємо з командою заздалегідь.

Як досягти Core Web Vitals при верстці сайтів на Бітрікс?

Critical CSS — виділяємо стилі першого екрану через пакет critical, інлайнимо в <head>. Решта завантажується асинхронно через media="print" onload="this.media='all'". LCP на мобільних скорочується на 1–1.5 секунди.

Зображення — головне гальмо. Використовуємо <picture> з WebP та JPEG-фолбеком. loading="lazy" для всього нижче першого екрану. width та height явно прописані — CLS = 0. Обробник в urlrewrite.php генерує WebP на льоту.

Мініфікація та стиснення. CSS та JS через Vite або вбудоване об'єднання Бітрікс. Brotli на nginx (brotli_comp_level 6) — на 15–20% ефективніше за gzip. Кешування статики: expires 1y + версіонування через query string.

Ми готові зробити аудит вашого проєкту та запропонувати конкретні кроки. Закажіть консультацію.

Що входить в послугу верстки сайтів на 1С-Бітрікс?

Після замовлення верстки шаблону або адаптації готового рішення передаємо:

• Вихідні коди шаблонів компонентів з розділенням на template.php, result_modifier.php, epilog
• CSS та JS, підключені через Asset — без інлайн-стилів
• Налаштоване кешування з тегами
• Документацію за структурою та параметрами
• Доступ до Git-репозиторію з історією змін
• Навчання вашого розробника: як правити шаблон без втрати оновлюваності

Гарантуємо відповідність Core Web Vitals та кросбраузерність. Закріплюємо інженера з досвідом 10+ років.