Stencil.js: создание веб-компонентов

TL;DR

Stencil.js — компилятор для создания повторно используемых веб‑компонентов на TypeScript и JSX. Быстро настраивается, генерирует совместимые с современными браузерами пакеты и даёт выбор стилей — inline, внешние файлы или Shadow DOM. Подойдёт, если вам нужны стандартизованные custom elements, интегрируемые в разные приложения.

Что такое веб‑компоненты?

Веб‑компоненты — это набор стандартов (Custom Elements, Shadow DOM, HTML Templates), которые позволяют создавать инкапсулированные, переиспользуемые элементы интерфейса. Один‑два предложения: Custom Element — это настраиваемый HTML‑тег; Shadow DOM изолирует стили и DOM.

Знакомство со Stencil.js

Stencil.js — это компилятор, который упрощает разработку веб‑компонентов с использованием TypeScript и JSX. Он генерирует код, совместимый с современными браузерами, и предоставляет API для декларативного определения компонента, его шаблона и стилей.

Важно: Stencil генерирует нативные web components, но сам по себе — не полноценный фронтенд‑фреймворк. Он фокусируется на компонентной библиотеке.

Установка и первый запуск

Инициализация проекта выполняется через npm. В терминале Node.js запустите:

npm init stencil  

Появится интерактивный выбор шаблона. Выберите опцию “component”, укажите имя проекта и подтвердите.

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

cd first-stencil-project  
npm install  

Структура и создание компонента

Обычно компоненты располагают в папке src/components. Для компонента “my-button” создайте файлы:

• src/components/my-button/my-button.tsx — логика и шаблон (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: имя HTML‑тега компонента.
• styleUrl / style / styleUrls: параметры подключения стилей.
• shadow: true/false — использовать Shadow DOM или нет.

Варианты добавления стилей

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

1. styleUrl — один внешний CSS-файл (пример выше).

2. style — inline‑строка с CSS:

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  
    );  
  }  
}  

3. styleUrls — массив внешних файлов:

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  
    );  
  }  
}  

Выбор способа зависит от задач: Shadow DOM + styleUrl даёт инкапсуляцию, inline‑style удобен для маленьких компонентов, styleUrls — для сложных сценариев с несколькими файлами.

Рендеринг компонента на странице

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

При сборке Stencil генерирует ESM‑и UMD‑версии; подключайте нужную для вашей цели.

Когда Stencil.js подходит и когда нет

Подходит, если:

• Нужны переиспользуемые, стандартизованные custom elements.
• Требуется интеграция компонентов в разные приложения (фреймворк‑агностично).
• Хотите использовать TypeScript и JSX при создании web components.

Не подходит, если:

• Нужен full‑stack фреймворк с маршрутизацией, состоянием и CLI для приложений (в этом случае лучше выбрать React/Vue/Angular).
• Требуется минимальная зависимость и вы готовы писать нативные web components вручную.

Альтернативы

• Lit — лёгкая библиотека для создания web components с удобной реактивностью.
• Vanilla custom elements — без инструментов, максимум контроля и минимум абстракций.
• Svelte / React / Vue — лучше для полного приложения, но не всегда оптимальны для создания framework‑agnostic библиотек компонентов.

Мини‑методология разработки компонента

1. Определите задачу и API компонента (атрибуты, события, slot’ы).
2. Напишите минимальный шаблон и тестируемый интерфейс.
3. Добавьте стили и подумайте о Shadow DOM (инкапсуляция vs theming).
4. Напишите unit‑тесты и E2E при необходимости.
5. Соберите и протестируйте интеграцию в целевых приложениях.

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

• Компонент рендерится без ошибок в целевых браузерах.
• Стандартные атрибуты работают и документированы.
• Стили не «протекают» туда, куда не должны (если применим Shadow DOM).
• Есть тесты на базовую функциональность.

Чек‑лист перед публикацией

• Сборка проходит без ошибок.
• Производительность проверена (первичный рендер приемлемый).
• Документация по API готова.
• Тесты и accessibility‑проверки пройдены.
• Версионирование и changelog обновлены.

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

• Custom Element — настраиваемый HTML‑тег.
• Shadow DOM — инкапсулированный DOM и CSS.
• TSX — JSX в синтаксисе TypeScript.

Когда Stencil не справится (пример)

Если проект требует полного набора функций приложения (маршрутизация, глобальное управление состоянием, сложное серверное рендеринг), то Stencil как инструмент библиотек компонентов не заменит фреймворк для разработки приложения.

Резюме

Stencil.js даёт систематизированный способ создавать веб‑компоненты на TypeScript и JSX. Он удобен для библиотек компонентов, легко интегрируется в разные приложения и поддерживает несколько вариантов стилей и сборки. Если вам нужны стандартизованные, переиспользуемые элементы интерфейса — Stencil стоит рассмотреть.

Ключевые действия: инициализируйте проект через npm, создайте папку src/components, опишите @Component с tag и стилями, соберите бандлы и подключите их в HTML.