Чому Web Components ламаються під час вбудовування в чужий інтерфейс
Компонент, який на ізольованій вітрині виглядає бездоганно, потрапляє в наявний інтерфейс і розсипається: заголовки наїжджають, кнопка втрачає відступи, модальне вікно йде під чужий шар.
Shadow DOM ізолює правила, але не скасовує наслідування: глобальні скидання й типографіка хоста дотягуються до слотового контенту, а через CSS-змінні всередину протікає тема застосунку.
Ізоляція стилів компонента виявляється домовленістю, а не гарантією. Перейменували в хості токен — компонент мовчки перефарбувався; змінили спосіб підключення шрифту — поїхала сітка.
Такі конфлікти стилів майже не видні на демо-сторінці: вони спливають на реальних даних, у темній темі та на довгих рядках.
Далі підключається стан і збірка. Фреймворки передають дані по-різному — рядковим атрибутом, властивістю або реактивним оновленням, — і частина змін усередині компонента залишається для хоста невидимою.
Подія з вкладеного вузла приходить як подія самого компонента, і обробники спрацьовують не там, де їх чекають. Дві версії одного набору в збірці дають зайву вагу й суперечку про те, чий тег зареєструвався першим.
Окрема стаття — дублювання логіки: валідація форм, локалізація, форматування дат і тематизація розповзаються між застосунком і компонентами, бо в них немає спільного контракту. Нижче розбираємо, як це закривається на рівні токенів, меж і перевірок під час вбудовування.
Що дає єдиний набір компонентів на різних стеках
Компонент описується один раз за веб-стандартом Custom Elements і підключається як звичайний тег у React, Vue та Angular — без обгорток під кожен фреймворк.
Усередині працює тіньовий DOM: стилі й розмітка ізольовані, тому правило з дизайн-системи не перебивається каскадом застосунку. Поверх стандарту зручно взяти Lit: декларативні шаблони й реактивні властивості прибирають ручну роботу з життєвим циклом елемента.
Єдине джерело правди змінює економіку правок. Раніше кнопка, поле або таблиця жили в трьох репозиторіях і розходилися під час першої ж доопрацювання; тепер зміна вноситься один раз і приїжджає в усі інтерфейси одним релізом.
Дубльований код скорочується на третину й більше, а сама правка випускається того ж дня, а не трьома паралельними задачами.
Контракт взаємодії теж стає спільним: властивості та події описані один раз, а не переписуються під пропси кожного фреймворку. Перевірки поведінки пишуться проти стандарту й не дублюються на три платформи — один набір тестів покриває всі застосунки.
Звідси передбачуваність: однаковий стан компонента виглядає й поводиться однаково в адміністративній панелі, у клієнтському кабінеті та на лендінгу.
Вартість підтримки інтерфейсів падає не за рахунок скорочення, а за рахунок усунення розбіжностей: менше гілок коду, менше «особливостей» конкретного фреймворку, один порядок оновлення залежностей. Розбираємо, як такий шар вбудовується в наявні застосунки без переписування.
Способи пакування й постачання компонентів: порівняння
Спосіб постачання визначає, скільки роботи ляже на команди під час кожного оновлення набору компонентів.
Один і той самий код можна віддати як готовий пакет, як генеровану обгортку під конкретний стек або як вихідні коди в спільний репозиторій — і ціна підтримки в цих випадках різна.
Нижче варіанти, між якими реально обирають, з обмеженнями, що проявляються не на демо, а на третьому-четвертому релізі.
| Варіант | Коли підходить | Обмеження |
|---|---|---|
| Готовий пакет компонентів | Єдиний набір у кількох застосунках, оновлення централізоване | Теми задаються через кастомні властивості; серверний рендеринг потребує окремої підтримки |
| Обгортка під стек | Команди хочуть звичний синтаксис, типізацію й автодоповнення | Обгортку перезбираємо на кожен мажор; частину подій і слотів прокидаємо вручну |
| Пряме підключення бандла до сторінки | Вбудовування в сторінки на старому стеку, контентні системи, лендінги | Версії на сторінках розходяться, контролю залежностей немає — сумісність тримається вручну |
| Вихідні коди в спільному репозиторії | Потрібні форки й правки під себе | Оновлення не приїжджають самі; версіонування й регрес — на боці команди |
Як утримуємо зворотну сумісність
Версіонування компонентів прив’язуємо до контракту, а не до внутрішнього влаштування: властивості, події, слоти. Мажор змінюється тільки під час видалення або зміни сенсу атрибута, решта йде мінором.
Старі імена продовжують працювати один мажорний цикл, тому оновлення бібліотеки в одному сервісі не потребує синхронного релізу сусідніх.
Як ми впроваджуємо бібліотеку компонентів: етапи роботи
Впровадження бібліотеки на web components починається не з коду, а з інвентаризації продакшн-інтерфейсів. Поки немає карти наявних елементів і розбіжностей між ними, оцінка строків нічого не варта. Ми йдемо фіксованою послідовністю — від аудиту до передавання команді.
- Аудит інтерфейсу. Збираємо перелік екранів і розбираємо наявні елементи за частотою використання, розбіжностями в розмітці, станах і поведінці.
- Схема компонентів. Фіксуємо межі кожного елемента: що йде до спільного набору, що залишається локальним, які властивості та події стають публічним інтерфейсом.
- Прототип на стику фреймворків. Збираємо один-два компоненти й підключаємо їх у React, Vue та Angular — перевіряємо, що події, слоти й стилі поводяться передбачувано в кожному.
- Реалізація бібліотеки. Пишемо узгоджений набір, закриваємо стани, доступність і тему оформлення, налаштовуємо версіонування та публікацію внутрішнього пакета.
- Міграція екранів. Замінюємо старі реалізації поетапно, по одному маршруту за реліз, з можливістю відкату до попередньої версії інтерфейсу.
- Приймання результату. Проганяємо поведінкові та візуальні перевірки, звіряємо з макетами, фіксуємо частку покритих сценаріїв і список усвідомлених винятків.
- Передавання команді. Віддаємо репозиторій, документацію, правила релізу й оновлення залежностей, розбираємо влаштування на живому коді.
На кожному етапі є відчутний вихід: після аудиту — карта елементів, після прототипу — компонент, який однаково працює в усіх фреймворках, після передавання — команда, що розвиває бібліотеку сама.
Що залишається в проєкті: репозиторій, схеми, регламенти
Передаємо проєкт так, щоб команда замовника могла розвивати його без нашої участі. Передавання — це не архів зі збіркою, а набір артефактів, кожен із яких відповідає на своє питання: що змінювати, де межі, чим перевірити результат. Нижче — склад комплекту, який вирушає на бік замовника.
- Вихідний код компонентів. Репозиторій із пакетами: самі веб-компоненти, спільні стилі та токени теми, тонкі обгортки для фреймворків-споживачів. Збірка відтворюється однією командою на чистій машині.
- Документація бібліотеки. Публічний опис API кожного компонента: властивості, події, слоти, стани завантаження й помилки. Плюс приклади використання та вітрина з усіма варіантами оформлення.
- Схема залежностей. Граф «що від чого залежить»: де зовнішні пакети, які версії сумісні між собою і що станеться під час їх оновлення вгору.
- Регламент оновлень. Правила випуску версій: що вважається ламальною зміною, як піднімається мінор, як споживачі дізнаються про нову версію і в який строк переїжджають.
- Правила внесення змін. Угода щодо гілок і найменування задач, обов’язкові перевірки перед злиттям, вимоги до перевірки коду й до тестів на нову логіку.
- Набір перевірок. Регресія за компонентами, візуальні порівняння відображення, перевірка відповідності контрактів між компонентом і його обгортками, запуск усього цього на кожній зміні.
- Інструкції із запуску й випуску. Покроковий документ: підняти середовище, зібрати, налагодити, віддати реліз. Написаний під нового інженера, а не під автора коду.
Такий комплект закриває головний ризик передавання: замовник бачить, де закінчується наша робота й починається його зона відповідальності. Першу самостійну правку команда робить разом із нами, на другій ми вже не потрібні.
Кейс: як прибрали дублювання інтерфейсів у чотирьох продуктах
Чотири продукти однієї компанії — кабінет клієнта, адмін-панель, публічний портал і мобільна веб-версія — розвивалися різними командами й з часом розійшлися в деталях.
Ключові блоки інтерфейсу — таблиці із сортуванням і посторінковим виведенням, фільтри, форми, вибір дати, завантаження файлів — існували в 9–14 копіях кожен.
Точка старту
Копії жили своїм життям: в одній таблиці клавіатурна навігація працювала, в іншій — ні, фільтр у панелі оператора скидався не так, як у кабінеті, а перевірка полів відрізнялася правилами.
Правка однієї поведінки потребувала синхронної роботи в чотирьох репозиторіях, і розбіжність спливала вже на прийманні — частка дефектів інтерфейсу, знайдених після випуску, трималася близько третини.
Що зробили
Спільні блоки звели в єдиний шар на Web Components: компонент збирається й перевіряється один раз, а в React, Vue та Angular підключається як звичайний елемент — без копій розмітки, стилів і логіки валідації.
Стилі, поведінка й набори перевірок лежать в одному репозиторії з однією версією та одним журналом змін, тому один продукт більше не може відстати від інших у поведінці блоку.
| Показник | До | Після |
|---|---|---|
| Копій одного блоку | 9–14 | 1 |
| Репозиторіїв на одну правку | 4 | 1 |
| Набір перевірок на блок | свій у кожному продукті | спільний |
| Дефекти інтерфейсу після випуску | близько третини | поодинокі |
Переходили поступово: нові екрани одразу збирали зі спільного шару, старі копії замінювали в міру планових доопрацювань, тому переписувати продукти повністю не довелося.
Час на доопрацювання типового блоку скоротився в рази, а відкат до попередньої версії компонента тепер робиться однією операцією для всіх продуктів одразу.
Чим Web Components відрізняються від звичайної бібліотеки інтерфейсів
Бібліотека інтерфейсів — це угода всередині одного стеку: компоненти живуть у моделі рендерингу конкретного фреймворку й збираються його інструментами. Поки продукт один і стек один, питання про переносність не виникає. Межа видна, коли той самий компонент потрібен в іншому застосунку або в чужому фреймворку.
Web Components переносять домовленості на рівень веб-платформи. Кастомний елемент — звичайний тег у розмітці, внутрішнє влаштування закрито тіньовим деревом: зовнішні стилі не протікають усередину, внутрішні не впливають на сторінку. Ізоляцію розмітки забезпечує браузер, а не угоди та лінтери.
Звідси різниця в залежності від стеку. Бібліотека тягне за собою середовище виконання фреймворку, її компонент не вставити в чужий застосунок без перезбирання. Кастомний елемент підключається імпортом і працює в будь-якому середовищі, де є браузерний DOM.
Вибір підходу — не про «сучасність», а про те, де проходить межа між продуктами. Якщо вона всередині однієї команди й одного стеку, бібліотеки достатньо. Якщо компоненти перетинають межі застосунків, ізоляцію розумніше робити на рівні платформи.
Часті технічні сумніви перед стартом проєкту
Сумніви перед стартом стосуються не самого стандарту — він стабільний і описаний, — а стиків: як вбудувати елементи в живий проєкт, хто їх супроводжуватиме, що робити зі старими браузерами і як випускати оновлення, не ламаючи сусідні модулі. Нижче — інженерні відповіді на те, що найчастіше запитують на технічних сесіях.
Чи можна впроваджувати в працюючий проєкт без переписування?
Так. Компоненти підключаються як звичайні теги й не потребують зміни збірки: React, Vue та Angular продовжують працювати як раніше, а спільні елементи живуть в одному місці. Починаємо з одного блоку — шапки або віджета оплати — і переносимо решту в міру потреби. Переписувати весь інтерфейс одразу не потрібно.
Чи зможемо ми підтримувати це своїми силами?
Так, якщо передаємо код, перевірки й документацію за контрактами елементів: які атрибути компонент приймає, які події віддає, що вважається ламальною зміною. Знання за межами платформи браузера не потрібні. Передавання ведемо на живому коді, щоб ваш розробник одразу вносив правки сам.
Що зі старими браузерами та вбудованими поданнями?
Ключові можливості стандарту підтримуються в усіх актуальних браузерах, зокрема мобільних. Для застарілих версій додаємо шар сумісності й проєктуємо деградацію: якщо елемент не піднявся, користувач бачить осмислену розмітку, а не порожнє місце. Перевіряємо на реальних пристроях, а не лише в емуляторі.
Як оновлювати компоненти, не ламаючи чужі модулі?
Кожен елемент версіонується окремо й публікується самостійним пакетом, тому оновлення одного блоку не тягне за собою решту. Контракт — атрибути, події, слоти — фіксуємо й змінюємо тільки в мажорній версії, а перед випуском проганяємо перевірки сумісності. Сусідні команди переходять на нову версію тоді, коли готові.
Обговоримо задачу й повернемося з оцінкою та планом робіт
Щоб повернутися з оцінкою обсягу робіт і планом впровадження, нам не потрібен повний технічний розбір — достатньо кількох вступних, решту інженери зберуть самі на дзвінку з вашою командою. Чим точніші вступні, тим менше припущень у строках етапів і складі команди.
Що корисно додати до опису задачі:
- Список фреймворків та їхні актуальні гілки у ваших застосунках — від цього залежить, скільки адаптерів і обгорток увійде до плану впровадження.
- Перелік інтерфейсних блоків, які мають стати спільними: форми, таблиці, фільтри, повідомлення, віджети.
- Посилання на репозиторій або вивантаження структури проєкту — так ми оцінимо складальний контур і точки інтеграції без здогадів.
- Вимоги до тематизації: світла й темна теми, брендування, доступність і клавіатурна навігація.
- Обмеження щодо браузерів і середовищ, зокрема застарілі версії, які все ще в проді.
- Склад вашої команди та зони відповідальності: хто погоджує архітектуру, хто перевіряє зміни, хто відповідає за реліз.
- Очікувані строки етапів і жорсткі дати — прив’язка до релізу або міграції змінює порядок робіт.
Після короткого дзвінка фіксуємо оцінку обсягу робіт, склад команди та строки етапів. План впровадження розбиваємо на незалежні кроки, щоб першу спільну бібліотеку web components можна було підключити, не чекаючи на переведення всіх застосунків.
Опишіть задачу — повернемося з оцінкою та планом.
