Headless-фронтенд на Vue.js для 1С-Бітрікс: розробка під ключ

Типова ситуація: дизайнер намалював каталог з анімованими фільтрами, миттєвим оновленням кошика та переходами між сторінками без перезавантаження. Фронтенд-розробник дивиться на шаблони bitrix:catalog.section і bitrix:sale.order.ajax — і розуміє, що вписати це в стандартну компонентну модель Бітрікс неможливо без костилів. Тут і з'являється headless-підхід: Бітрікс залишається бекендом, а весь інтерфейс живе на Vue.js. Це не модний стек заради моди. Headless виправданий, коли стандартні шаблони Бітрікс не дозволяють реалізувати необхідний UX, коли фронтенд-команда працює автономно від бекенд-розробників, або коли один API обслуговує сайт, мобільний додаток та кіоски в офлайн-точках. Ми використовуємо цей підхід понад 5 років і за цей час реалізували більше 20 проєктів — від невеликих каталогів до B2B-порталів з десятками тисяч товарів. Досвід показує: при грамотній архітектурі headless дає сучасний UX і високу продуктивність, а гарантія на роботи становить 12 місяців.

Чому headless на Бітрікс — виправдане рішення?

Для проєктів, де стандартний інтерфейс Бітрікс не підходить за вимогами до анімації, швидкості переходу або необхідності працювати на мобільних пристроях з відключеним JavaScript (SSR). Headless також дозволяє розділити команди: фронтенд-розробники працюють з Vue, бекенд — з Бітрікс, а контрактом служить API-специфікація. Крім того, такий підхід природно готує ґрунт для мультиплатформенності — один API обслуговує сайт, додаток та кіоски. Окупність інвестицій в headless становить близько 6–12 місяців завдяки зниженню витрат на підтримку фронтенду до 30%.

Архітектура: як розділяються шари

У класичному Бітрікс-магазині PHP-компонент робить вибірку, передає масив у template.php, там же підключається CSS і JS. У headless-схемі все інакше:

• Бітрікс працює як API-сервер. Каталог, ціни, залишки, кошик, оформлення, авторизація — все через REST API (модуль rest) або кастомні контролери на базі \Bitrix\Main\Engine\Controller.
• Vue.js / Nuxt.js — окремий додаток. Рендерить інтерфейс, керує маршрутизацією, станом, формами.
• Nginx проксіює: /api/* йде в Бітрікс, решта — на статику Vue або Node.js (при SSR).

Деплой фронтенду та бекенду незалежний. Фронтенд-розробник пушить у свій репозиторій, CI збирає бандл, розгортає на CDN або Node-сервер. Бекенд-розробник оновлює Бітрікс окремо. Контракт між ними — API-специфікація.

REST API Бітрікс: що працює, а що доведеться дописувати

Модуль rest надає методи для основних сутностей магазину:

• catalog.product.list — товари з фільтрацією за властивостями, секцією, ціною
• catalog.product.get — детальна картка
• catalog.product.offer.list — торгові пропозиції (SKU)
• catalog.section.list — дерево категорій
• catalog.price.list — ціни за типом
• sale.basket.addItem, sale.basket.updateItem, sale.basket.deleteItem, sale.basket.getItems
• sale.order.add, sale.order.get, sale.order.list
• sale.shipment.getDeliveryServices, sale.paySystem.getList

На папері все покрито. На практиці починаються нюанси. catalog.product.list не повертає довільні властивості інфоблоку. Потрібно додатково запитувати через catalog.product.getFieldsByFilter або писати свій endpoint. Фасетна фільтрація — підрахунок кількості товарів за кожним значенням фільтра, як у стандартному smart_filter — у REST API відсутня. Розрахунок вартості доставки за вмістом кошика — ще один метод, якого немає з коробки.

Рішення — кастомні REST-методи. Реєструються через \CRestServer::onRestServiceBuildDescription() або через \Bitrix\Main\Engine\Controller з анотацією @restMethod. На стороні Бітрікс кастомний контролер виконує вибірку та повертає JSON:

• /api/catalog/filter — товари + фасети (кількість за значеннями фільтра)
• /api/cart/calculate — перерахунок кошика з урахуванням правил кошика, знижок та промокодів
• /api/checkout/submit — оформлення замовлення одним запитом

Фасетний індекс — окрема історія. Бітрікс зберігає попередньо розраховані фасети в таблиці b_catalog_smart_filter. При headless-підході потрібно або використовувати цю таблицю напряму через ORM, або будувати фасети на льоту. Перший варіант швидший, але прив'язує до внутрішньої структури Бітрікс. Другий — повільніший на великих каталогах (50 000+ товарів), зате передбачуваний. Згідно з Wikipedia, REST — архітектурний стиль взаємодії компонентів розподіленого додатку в мережі.

Компонентна архітектура Vue-додатку

Структура фронтенду для інтернет-магазину:

src/ ├── pages/ │ ├── CatalogPage.vue # список товарів з фільтрами │ ├── ProductPage.vue # картка товару │ ├── CartPage.vue # кошик │ ├── CheckoutPage.vue # оформлення │ └── AccountPage.vue # особистий кабінет ├── components/ │ ├── catalog/ │ │ ├── ProductCard.vue │ │ ├── FilterPanel.vue │ │ └── FacetCounter.vue │ ├── cart/ │ │ ├── CartItem.vue │ │ └── CartSummary.vue │ └── ui/ # перевикористовувані елементи ├── stores/ │ ├── catalogStore.ts # Pinia: товари, фільтри, пагінація │ ├── cartStore.ts # кошик, синхронізація з API │ ├── userStore.ts # авторизація, токен │ └── checkoutStore.ts # оформлення замовлення ├── api/ │ ├── catalog.ts # обгортки над API каталогу │ ├── cart.ts │ └── auth.ts └── composables/ ├── useProductFilter.ts # логіка фільтрації └── useInfiniteScroll.ts # нескінченна прокрутка 

Pinia керує станом. cartStore — найнетривіальніший: при додаванні товару потрібно миттєво оновити UI (optimistic update), відправити запит до API, отримати відповідь з актуальною ціною (Бітрікс міг застосувати знижку або списати залишок) і синхронізувати локальний стан з сервером. Для неавторизованих користувачів кошик живе в localStorage і мігрує на сервер після логіну. Vue Router з lazy-loading: кожна сторінка — окремий chunk. Переходи між категоріями не перезавантажують додаток, а фільтри записуються в query-параметри URL для можливості поділитися посиланням.

Як налаштувати SSR для індексації?

Vue SPA рендериться на клієнті. Пошуковий робот бачить порожній <div id="app"></div>. Для інтернет-магазину, де картки товарів і категорії повинні індексуватися, це вирок.

Nuxt.js з SSR — основний варіант. Node.js-сервер рендерить Vue-компоненти в HTML, дані з Бітрікс API запитуються через useFetch() або useAsyncData(). Клієнт отримує готовий HTML, після гідратації додаток працює як SPA. Використання SSR зменшує час до першого відображення на 40–60%.

Nuxt.js з ISR (Incremental Static Regeneration) — гібрид. Сторінки каталогу кешуються і оновлюються за TTL або за вебхуком з Бітрікс при зміні товару. Nuxt 3 підтримує routeRules з swr (stale-while-revalidate):

// nuxt.config.ts routeRules: { '/catalog/**': { swr: 3600 }, // кеш на годину '/product/**': { swr: 600 }, // кеш на 10 хвилин '/cart': { ssr: false }, // кошик — тільки клієнт '/checkout': { ssr: false }, } 

Для каталогів з 50 000+ товарів SSR кращий за повну статичну генерацію — nuxt generate для такого обсягу займе години. Мета-теги — окрема задача. У Бітрікс шаблони SEO налаштовуються у властивостях інфоблоку (шаблони виду {=this.Name} купити в Києві). У headless-підході ці шаблони потрібно віддавати через API і застосовувати в Nuxt через useHead() або useSeoMeta().

Авторизація: два підходи

OAuth 2.0 через модуль rest: фронтенд перенаправляє на /oauth/authorize/, користувач логіниться на стороні Бітрікс, отримує code, обмінює на access_token. Стандартний flow, але UX страждає — редирект на інший домен.

Кастомний JWT-endpoint: /api/auth/login приймає логін/пароль, Бітрікс перевіряє через CUser::Login(), створює сесію і повертає JWT. Фронтенд зберігає токен в httpOnly cookie (не в localStorage — інакше XSS-вразливість). Refresh-токен продовжує сесію без повторного введення пароля. Простіше в реалізації, UX краще.

Що втрачається при headless?

• Візуальний редактор — не працює. Контент керується через адмінку Бітрікс, фронтенд забирає дані по API.
• Композитний кеш — не застосовний. Кешування на стороні Nuxt (ISR) або CDN.
• Стандартні компоненти — bitrix:catalog.section, bitrix:sale.order.ajax не використовуються. Вся логіка відображення на Vue.
• Обмін з 1С — працює без змін, це серверна сторона.

Які етапи включає розробка?

1. Аналіз — вивчаємо поточну архітектуру Бітрікс, вимоги до UX та продуктивності, визначаємо перелік кастомних API-методів.
2. Проектування — розробляємо API-специфікацію (OpenAPI), прототип інтерфейсу, узгоджуємо з вами.
3. Розробка — пишемо кастомні REST-методи, Vue-додаток, налаштовуємо SSR, інтегруємо із зовнішніми сервісами.
4. Тестування — навантажувальне тестування (за допомогою k6 або Artillery), перевірка SEO-метатегів, кросбраузерність.
5. Деплой — налаштування CI/CD, розгортання на production, моніторинг.

Що входить в роботу?

• Повна API-специфікація (OpenAPI) для всіх кастомних методів.
• Вихідний код Vue-додатку з коментарями.
• Інструкція з розгортання та налаштування CI/CD.
• Автоматичні тести на критично важливі сценарії.
• Навчання вашої команди роботі з headless-архітектурою.
• 1 місяць технічної підтримки після запуску.

Терміни за масштабом проєкту:

Headless на Бітрікс — компроміс. Сучасний фронтенд і гнучкість в обмін на втрату частини екосистеми та збільшення вартості підтримки. Підхід виправданий для проєктів з високими вимогами до інтерфейсу, виділеною фронтенд-командою та планами на мультиплатформенність. Перехід на headless дозволяє скоротити витрати на підтримку фронтенду до 30% за рахунок незалежності команд. Щоб оцінити ваш проєкт, зв'яжіться з нами — ми підготуємо комерційну пропозицію з точними термінами та вартістю. Замовте консультацію з headless-розробки для вашого інтернет-магазину.