Постепенная миграция

Stencil изначально проектировался как инструмент, способный встраиваться в существующие экосистемы без необходимости полного переписывания приложения. Ключевая идея — использование Web Components как нейтрального слоя, который может сосуществовать с любым фреймворком или вовсе без него. Это делает Stencil особенно подходящим для поэтапной миграции крупных фронтенд-проектов, где мгновенный переход невозможен из-за масштаба, рисков или организационных ограничений.

Постепенная миграция предполагает одновременное существование старого стека и нового решения на базе Stencil с контролируемым увеличением доли компонентов, реализованных через Web Components.

Архитектурная основа: Web Components как контракт

Stencil компилирует компоненты в стандартные Web Components, опираясь на спецификации Custom Elements, Shadow DOM и ES Modules. Это создает четкий архитектурный контракт:

компоненты изолированы стилями;
API компонента выражено через HTML-атрибуты, свойства и события;
отсутствует жесткая привязка к конкретному фреймворку исполнения.

Благодаря этому Stencil-компонент может быть использован:

внутри legacy-приложений на jQuery;
в Angular, React, Vue и других SPA;
в серверных шаблонах без клиентского фреймворка.

Стратегии внедрения Stencil в существующий проект

Выделение дизайн-системы

Наиболее распространенный сценарий — вынос UI-библиотеки в отдельный пакет на базе Stencil. Существующее приложение продолжает работать без изменений, но новые визуальные элементы реализуются как Web Components.

Преимущества подхода:

единый источник UI-логики;
независимый цикл релизов;
постепенное замещение старых компонентов.

Stencil хорошо подходит для реализации:

кнопок, форм, модальных окон;
навигационных элементов;
сложных, но переиспользуемых виджетов.

Инкапсуляция сложных участков интерфейса

В больших кодовых базах часто существуют зоны с высокой сложностью и плохой поддерживаемостью. Такие участки могут быть инкапсулированы в Web Components без изменения остальной архитектуры.

Процесс выглядит следующим образом:

Выделяется функциональный блок (например, таблица с фильтрацией).
Он переписывается как Stencil-компонент.
Встраивается в существующий DOM как обычный HTML-тег.

Stencil позволяет:

полностью скрыть внутреннюю реализацию;
сократить связность с глобальным состоянием;
ограничить побочные эффекты.

Интеграция со старыми фреймворками

Angular

Stencil официально поддерживает генерацию Angular-оберток. В процессе сборки создаются прокси-компоненты, которые:

корректно работают с change detection;
пробрасывают input/output;
не требуют ручной настройки.

Stencil-компоненты могут использоваться параллельно с Angular-компонентами, что позволяет мигрировать экран за экраном.

React

В React используется механизм Custom Elements с дополнительными прокси-компонентами для корректной типизации и обработки событий.

Особенности:

события Web Components не являются Synthetic Events;
требуется явная привязка обработчиков;
поддержка JSX обеспечивается через autogenerated typings.

Этот подход позволяет постепенно заменять React-компоненты, не меняя структуру приложения.

Legacy-код без фреймворков

Stencil-компоненты могут использоваться напрямую через HTML-разметку:

<my-datepicker value="2025-01-01"></my-datepicker>

Коммуникация осуществляется через:

DOM-события;
публичные методы компонента;
наблюдаемые атрибуты.

Это особенно полезно при миграции старых серверных приложений с минимальным JavaScript.

Управление состоянием при миграции

Stencil не навязывает конкретную модель state management. Это критично для поэтапного перехода.

Возможные варианты:

локальное состояние внутри компонента;
передача данных через props;
использование глобального хранилища вне Stencil (Redux, MobX, Signals);
синхронизация через события.

Stencil-компоненты могут выступать как:

полностью автономные элементы;
визуальные оболочки над внешним состоянием.

Это позволяет не ломать существующую логику управления данными.

Работа со стилями в смешанной среде

Stencil по умолчанию использует Shadow DOM, что:

предотвращает конфликты CSS;
позволяет внедрять компоненты в нестабильные legacy-стили.

При необходимости Shadow DOM может быть отключен, если:

требуется интеграция с глобальными стилями;
используется старый CSS-фреймворк;
необходим полный контроль над каскадом.

Stencil поддерживает:

scoped styles;
CSS Variables для темизации;
динамическое переключение тем без пересборки.

Совместимость и полифиллы

Для поддержки старых браузеров Stencil автоматически подключает необходимые полифиллы. Это особенно важно при миграции, где часть пользователей может работать в устаревших окружениях.

Stencil:

определяет возможности браузера;
загружает только нужные полифиллы;
не увеличивает нагрузку на современные платформы.

Таким образом, внедрение Web Components не ухудшает существующие SLA по производительности.

Организация монорепозитория и пакетов

При постепенной миграции часто используется следующая структура:

legacy-приложение;
пакет с Stencil-компонентами;
адаптеры для конкретных фреймворков.

Stencil хорошо работает в:

monorepo (Nx, Turborepo, pnpm);
multi-package репозиториях;
независимых npm-пакетах.

Это упрощает:

контроль версий;
откат изменений;
параллельную разработку.

Тестирование в условиях гибридной архитектуры

Stencil поддерживает:

unit-тесты компонентов;
e2e-тесты через Playwright;
снапшот-тестирование Shadow DOM.

Stencil-компоненты могут тестироваться независимо от legacy-кода, что:

снижает сложность тестов;
ускоряет CI;
уменьшает количество регрессий при миграции.

Критерии завершения миграции

Постепенная миграция не обязательно предполагает полный отказ от старого фреймворка. В ряде случаев Stencil остается:

основой дизайн-системы;
слоем между микрофронтендами;
универсальной библиотекой UI.

Если же цель — полная замена, Stencil-компоненты уже готовы к использованию в любом новом окружении без переписывания, что делает финальный этап миграции технически простым и предсказуемым.