Розробка decoupled-фронтенду для 1С-Бітрікс

Розробка decoupled-фронтенду для 1С-Бітрікс

Decoupled — це коли фронтенд фізично відокремлений від Бітрікс: живе на власному сервері, деплоїться незалежно, використовує власний стек (React, Vue, Next.js), а з Бітрікс спілкується лише через API. На відміну від чистого headless, decoupled може зберігати частину сторінок на Бітрікс-шаблонах — наприклад, адміністративну панель або сторінки, що генеруються CMS.

Коли потрібен decoupled

Decoupled виправданий, коли поточний Бітрікс-шаблон став обмеженням за продуктивністю або можливостями UX, але переписувати все одразу немає можливості. Типові сценарії:

• Каталог товарів замінюється на React SPA, решта сторінок залишається на Бітрікс-шаблоні
• Особистий кабінет клієнта переписується на Vue, решта — без змін
• Мобільний застосунок отримує дані з Бітрікс через API, веб-сайт залишається на шаблоні

Це еволюційний підхід: поступово замінюєте частини сайту, не влаштовуючи повний редизайн.

Патерн «острів» — часткова інтеграція фронтенду

Замість повного відокремлення фронтенду ви вбудовуєте React-компоненти в існуючий Бітрікс-шаблон через точки монтування:

// У шаблоні компонента каталогу Бітрікс
// /local/templates/main/components/bitrix/catalog/my_template/template.php

// Дані для React передаємо через data-атрибут або глобальну змінну
$catalogData = json_encode($arResult['ITEMS']);
?>
<div id="react-catalog"
     data-items="<?= htmlspecialchars($catalogData) ?>"
     data-currency="UAH">
</div>

<script src="/local/js/dist/catalog.bundle.js"></script>
<script>
  window.BitrixCatalog && window.BitrixCatalog.mount(
    document.getElementById('react-catalog'),
    <?= $catalogData ?>
  );
</script>

// catalog.bundle.js — збирається Webpack/Vite незалежно
import { createRoot } from 'react-dom/client';
import { CatalogApp } from './CatalogApp';

window.BitrixCatalog = {
    mount(container, initialData) {
        const root = createRoot(container);
        root.render(<CatalogApp initialData={initialData} />);
    }
};

Цей підхід дозволяє розробляти фронтенд на React з повноцінним toolchain (TypeScript, hot reload, тести) і при цьому не чіпати решту Бітрікс-сайту.

Конфігурація збірки (Vite)

// vite.config.js для decoupled-компонентів Бітрікс
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
    plugins: [react()],
    build: {
        outDir: '../public/local/js/dist',
        lib: {
            entry: './src/index.tsx',
            name: 'BitrixComponents',
            formats: ['iife'], // IIFE для вбудовування в Бітрікс-шаблон
            fileName: 'components',
        },
        rollupOptions: {
            external: [], // не екстерналізуємо залежності
        },
    },
    server: {
        cors: true, // дозволяємо CORS для dev-сервера
        port: 3000,
    },
});

У режимі розробки Vite dev-сервер запускається на localhost:3000, а Бітрікс-сайт — на site.local. Звернення до API з dev-сервера проксуються через Vite proxy:

server: {
    proxy: {
        '/api': {
            target: 'http://site.local',
            changeOrigin: true,
        }
    }
}

Управління станом між Бітрікс і React

Найскладніша частина decoupled — синхронізація стану між Бітрікс-частиною та React-компонентами. Кошик — класичний приклад: іконка кошика в Бітрікс-шапці має показувати актуальну кількість товарів, доданих через React-каталог.

Рішення через кастомний Event Bus:

// shared/eventBus.js — доступний і в Бітрікс-частині, і в React
window.BitrixEventBus = {
    listeners: {},
    emit(event, data) {
        (this.listeners[event] || []).forEach(cb => cb(data));
    },
    on(event, callback) {
        (this.listeners[event] ||= []).push(callback);
    }
};

// У React-компоненті при додаванні до кошика:
window.BitrixEventBus.emit('cart:updated', { count: newCount });

// У Бітрікс-шаблоні (шапка):
window.BitrixEventBus.on('cart:updated', ({ count }) => {
    document.querySelector('.cart-counter').textContent = count;
});

Деплой і CI/CD

Decoupled-фронтенд потребує окремого кроку збірки в CI/CD. Простий pipeline для GitLab CI:

build-frontend:
  stage: build
  script:
    - cd frontend
    - npm ci
    - npm run build
    - rsync -avz dist/ server:/var/www/site/local/js/dist/
  only:
    - main

Після деплою фронтенду Бітрікс-шаблони автоматично підхоплюють нову версію бандлу. Версіонуйте файли за хешем вмісту (catalog.a1b2c3.js), щоб уникнути проблем із браузерним кешем.

Decoupled — розумний компроміс між «все переписати» і «залишити як є». Дозволяє модернізувати фронтенд поступово, знижує ризики та дає реально оцінити віддачу від інвестицій у новий стек до повного переходу.