Stencil.js — быстрые и совместимые веб‑компоненты

Веб‑компоненты — это набор технологий для создания переиспользуемых элементов интерфейса, которые можно использовать в разных веб‑приложениях. Stencil.js упрощает создание таких компонентов: он компилирует исходный код в чистые веб‑компоненты, оптимизирует их и делает совместимыми с современными браузерами.

Начало работы со Stencil.js

Чтобы начать, нужно инициализировать проект на компьютере. Откройте терминал Node.js и запустите команду инициализации:

npm init stencil

После запуска вы увидите интерактивный выбор шаблона проекта в терминале:

Выберите опцию компонента, введите имя проекта и подтвердите выбор.

Перейдите в папку проекта и установите зависимости:

cd first-stencil-project
npm install

Создание нового веб‑компонента

По умолчанию структура включает папку src/components. В ней каждый компонент — это папка с TypeScript/TSX файлом и CSS (или другим стилевым файлом). Stencil использует TypeScript и JSX/TSX для описания разметки.

Например, чтобы создать компонент my-button, добавьте файлы src/components/my-button/my-button.tsx и src/components/my-button/my-button.css и определите компонент так:

import { Component, h } from '@stencil/core';

@Component({
  tag: 'my-button',
  styleUrl: 'my-button.css',
  shadow: true,
})

export class MyButton {
  render() {
    return (
      Click Me
    );
  }
}

Короткие пояснения:

• Декоратор @Component принимает объект настроек: tag — имя тега, styleUrl — файл стилей, shadow — включение Shadow DOM.
• h — функция для создания виртуальной разметки (аналога React.createElement).

Варианты подключения стилей

Stencil поддерживает несколько способов подключения стилей:

• styleUrl — одиночный внешний CSS/SCSS файл.
• styleUrls — массив путей к файлам.
• style — строка с inline CSS.

Пример inline style:

import { Component, h } from '@stencil/core';

@Component({
  tag: 'my-button',
  style: `
    button {
      padding: 1rem 0.5rem;
      border-radius: 12px;
      font-family: cursive;
      border: none;
      color: #e2e2e2;
      background-color: #333333;
      font-weight: bold;
    }
  `,
  shadow: true,
})

export class MyButton {
  render() {
    return (
      Click Me
    );
  }
}

Пример нескольких файлов стилей:

import { Component, h } from '@stencil/core';

@Component({
  tag: 'my-button',
  styleUrls: ['my-button.css', 'another-button.css'],
  shadow: true,
})

export class MyButton {
  render() {
    return (
      Click Me
    );
  }
}

Рендеринг компонента в HTML

После сборки вы можете подключить сборку к статическому HTML и использовать тег компонента:

При сборке Stencil генерирует файлы в папке build, которые содержат ESM и UMD вариации для включения на страницу.

Лучшие практики и рекомендации

• Используйте Shadow DOM для изоляции стилей, если компонент должен быть независимым от внешних стилей. Если же нужен перекрываемый дизайн — не используйте Shadow.
• Пишите компоненты в TypeScript для явной типизации.
• Экспортируйте только публичный API через свойства (@Prop), события (@Event) и методы (@Method).
• Минимизируйте размер пакета: отключайте ненужные полифиллы и используйте lazy loading для тяжёлых зависимостей.
• Пишите тесты для рендеринга и взаимодействий.

Когда не стоит использовать Stencil

• Для очень простых сайтов без повторно используемых UI элементов полноценный компилятор может быть избыточен.
• Если проект целиком на фреймворке, где уже есть устоявшаяся экосистема компонентов и интеграция (например, когда нужна tight React‑интеграция), возможно, проще использовать нативные компоненты библиотек.

Модель принятия решений

flowchart TD
  A[Нужен переиспользуемый UI] --> B{Требуется ли изоляция стилей?}
  B -- Да --> C[Использовать Stencil с Shadow DOM]
  B -- Нет --> D[Использовать Stencil без Shadow или обычную библиотеку]
  C --> E{Нужна интеграция с React/Angular?}
  D --> E
  E -- Да --> F[Экспортировать компоненты как веб‑компоненты и интегрировать]
  E -- Нет --> G[Использовать как standalone компоненты]

Тестирование и критерии приёмки

Критерии приёмки:

• Компонент рендерится в документе и отображает базовую разметку.
• Стили применяются ожидаемо (при использовании Shadow DOM — в изоляции).
• Публичные свойства работают и обновляют представление.
• События эмитятся корректно и ловятся потребителем.

Минимальные тесты:

• Unit: рендер компонента с дефолтными пропсами.
• Integration: событие клика приводит к ожидаемому результату.
• Visual: smoke‑test рендера в headless браузере.

Роли и чеклисты перед релизом

Разработчик:

• Типы проверены TypeScript.
• Есть unit‑тесты и пример использования.
• Минимальные стили вынесены.

Технический редактор/Проверяющий:

• Документация по API написана.
• Совместимость браузеров проверена.

Дизайнер:

• Проверены визуальные состояния (hover, focus, disabled).
• Есть запасные темы или CSS‑переменные.

Миграция и совместимость

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

Безопасность и конфигурация

• Не вставляйте HTML из ненадёжных источников в рендер без санитайзации.
• Контролируйте зависимости и обновляйте сборщики/плагины.
• Ограничьте права доступа к глобальным объектам внутри компонентов.

Короткий глоссарий

• Веб‑компонент — стандартизованный пользовательский элемент DOM.
• Shadow DOM — механизм инкапсуляции стилей и разметки.
• @Component — декоратор Stencil для описания метаданных компонента.

Контрольный пример использования

1. Инициализируйте проект: npm init stencil
2. Создайте компонент в src/components
3. Соберите проект: npm run build
4. Подключите файлы из /build в HTML и используйте тег компонента

Итог

Stencil.js ускоряет создание переиспользуемых и совместимых веб‑компонентов. Он подходит для библиотек компонентов и проектов, где важна совместимость и производительность. Выберите Shadow DOM, если вам нужна строгая инкапсуляция, или избегайте его для сквозной стилизации.

Важно

Перед использованием проведите тесты на целевых браузерах и договоритесь о контракте API компонента между командами.