Кастомизация компилятора

Stencil предоставляет гибкий механизм компиляции компонентов, позволяющий адаптировать процесс сборки под специфические требования проекта. Основой кастомизации является конфигурационный файл stencil.config.ts, где задаются опции компилятора, плагины и инструменты трансформации кода.

Конфигурация компилятора

Основной объект конфигурации имеет тип Config и включает ключевые параметры:

import { Config } from '@stencil/core';

export const config: Config = {
  namespace: 'my-components',
  outputTargets: [
    { type: 'dist' },
    { type: 'www' }
  ],
  globalStyle: 'src/global/app.css',
  tsconfig: 'tsconfig.json'
};

Ключевые моменты:

  • namespace — пространство имен, которое используется при генерации тегов веб-компонентов.
  • outputTargets — массив целей сборки, где каждая цель описывает формат вывода: dist для библиотек, www для веб-приложений.
  • globalStyle — глобальные стили, подключаемые к каждому компоненту.
  • tsconfig — путь к TypeScript-конфигурации, позволяющий контролировать строгую типизацию и поддерживаемые версии ECMAScript.

Пользовательские плагины компилятора

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

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

import { CompilerPlugin, CompilerCtx, BuildContext } from '@stencil/core/internal';

export const docPlugin: CompilerPlugin = {
  name: 'doc-plugin',
  async load(config, compilerCtx: CompilerCtx, buildCtx: BuildContext) {
    buildCtx.components.forEach(component => {
      console.log(`Генерация документации для: ${component.tagName}`);
    });
  }
};

Плагины подключаются в конфигурации через массив plugins:

export const config: Config = {
  namespace: 'my-components',
  plugins: [docPlugin]
};

Настройка JSX и транспиляции

Stencil использует собственный JSX-препроцессор. Компиляция JSX управляется через опции:

  • jsx — режим генерации кода: preserve, react или react-jsx.
  • hydrateClientSide — включение гидратации компонентов на стороне клиента.
  • sourceMap — генерация карты исходников для отладки.
export const config: Config = {
  namespace: 'my-components',
  tsconfig: 'tsconfig.json',
  buildEs5: true,
  sourceMap: true,
  copy: [{ src: 'assets', dest: 'build/assets' }]
};

Кастомизация CSS и Shadow DOM

Stencil позволяет настраивать обработку стилей на уровне компонентов:

  • scoped — использовать scoped CSS вместо Shadow DOM.
  • shadow — включить Shadow DOM для изоляции стилей.
  • styleUrl и styles — указание внешних и встроенных стилей для компонента.
  • Поддержка PostCSS и других препроцессоров через плагины.

Пример:

@Component({
  tag: 'my-button',
  styleUrl: 'my-button.css',
  shadow: true
})
export class MyButton {
  render() {
    return <button class="btn">Нажми меня</button>;
  }
}

Расширенные возможности трансформации

Stencil позволяет внедрять кастомные трансформации TypeScript и HTML:

  • transformers — массив функций для модификации AST перед генерацией кода.
  • Возможность внедрять автоматические импорты, генерацию типов или оптимизацию шаблонов.
  • Интеграция с ESLint и Prettier через плагины для стандартизации кода.

Контроль процесса сборки

Stencil предоставляет API для программного управления сборкой:

import { build } from '@stencil/core';

build({
  config: { namespace: 'custom-build' },
  devMode: false
}).then(() => console.log('Сборка завершена'));

Через API можно:

  • Включать или отключать режим разработки.
  • Управлять генерацией файлов и выводом на диск.
  • Отслеживать ошибки компиляции и предупреждения.

Оптимизация выходного кода

Компилятор Stencil позволяет управлять оптимизациями:

  • minifyJs и minifyCss — минификация кода и стилей.
  • hashedFileNames — добавление хешей к именам файлов для кэширования.
  • rollupPlugins — подключение дополнительных плагинов Rollup для трансформации и оптимизации бандла.
export const config: Config = {
  namespace: 'my-components',
  minifyJs: true,
  minifyCss: true,
  hashedFileNames: true
};

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

Оглавление