Структура проекта Stencil

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

Корневая директория

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

  • stencil.config.ts — основной конфигурационный файл, в котором задаются параметры сборки проекта, пути к исходным файлам и прочие настройки фреймворка.
  • package.json — стандартный файл для Node.js-проектов, в котором прописаны зависимости, скрипты сборки и прочая информация о проекте.
  • tsconfig.json — конфигурация TypeScript, которая определяет правила компиляции для проекта, такие как пути, версии и типы.
  • node_modules/ — каталог с зависимостями, установленными через npm или yarn.
  • dist/ — каталог, куда после сборки проекта помещаются скомпилированные файлы.
  • www/ — каталог для статики, куда могут быть собраны результаты сборки для дальнейшего развертывания.

Директория src

Каталог src является центральным для любого проекта на Stencil. Именно здесь находятся все исходные файлы компонентов и их логика.

Структура каталога src

  • components/ — здесь находятся все веб-компоненты проекта. Каждый компонент обычно имеет свою папку с файлами, описывающими его логику, стили и шаблон.
  • assets/ — папка для хранения статических ресурсов, таких как изображения, шрифты и прочие файлы, которые могут понадобиться компонентам.
  • global/ — файлы, которые касаются глобальных стилей и настроек проекта. Например, можно хранить здесь глобальные SCSS или другие ресурсы, которые должны быть доступны везде.
  • utils/ — утилиты и вспомогательные функции, которые используются в нескольких компонентах или сервисах.

Компоненты

Каждый компонент внутри каталога components представляет собой набор файлов:

  • component-name.tsx — основной файл компонента, написанный на JSX с TypeScript. В этом файле описываются структура компонента, его методы и жизненные циклы.
  • component-name.css или component-name.scss — файл стилей компонента. Stencil использует Web Components, что позволяет инкапсулировать стили внутри самого компонента, не влияя на внешний мир.
  • component-name.spec.ts — тесты для компонента. Stencil поддерживает написание тестов с использованием Jest или других тестовых фреймворков.

Конфигурация сборки

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

Пример простого конфигурационного файла:

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

export const config: Config = {
  namespace: 'my-component-library',
  globalStyle: 'src/global/style.css',
  globalScript: 'src/global/app.ts',
  outputTargets: [
    {
      type: 'www',
      serviceWorker: null,
    },
    {
      type: 'dist',
      esmLoaderPath: './loader',
    },
  ],
};

Здесь можно настроить:

  • namespace — название проекта, которое будет использоваться для всех компонентов.
  • globalStyle — путь к глобальным стилям проекта.
  • outputTargets — массив, в котором указываются типы сборки. Это могут быть как Web-компоненты для использования в других проектах, так и статическая версия для развертывания на сервере.

Тестирование

Проект Stencil поддерживает тестирование компонентов с использованием Jest. Каждый компонент может иметь собственный файл тестов с расширением .spec.ts. Эти файлы содержат тесты, которые проверяют корректность работы компонента и его методов.

Пример теста для компонента:

import { Component, h } from '@stencil/core';
import { newSpecPage } from '@stencil/core/testing';
import { MyComponent } from './my-component';

describe('my-component', () => {
  it('renders the component', async () => {
    const page = await newSpecPage({
      components: [MyComponent],
      html: `<my-component></my-component>`,
    });
    expect(page.root).toEqualHtml(`
      <my-component>
        <mock:shadow-root>
          <div>Hello, World!</div>
        </mock:shadow-root>
      </my-component>
    `);
  });
});

Этот тест проверяет, что компонент рендерится и правильно отображает содержимое.

Стилизация компонентов

Каждый компонент в Stencil может иметь свои стили, которые инкапсулируются в рамках компонента, чтобы не влиять на остальную часть приложения. Стандартно Stencil поддерживает CSS и SCSS, а также стили в формате Shadow DOM, что позволяет полностью изолировать визуальную составляющую компонента.

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

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

@Component({
  tag: 'my-component',
  styleUrl: 'my-component.css',
  shadow: true,
})
export class MyComponent {
  render() {
    return (
      <div class="my-component">
        <p>Hello, World!</p>
      </div>
    );
  }
}

Здесь используется атрибут shadow: true, который включает Shadow DOM, обеспечивая инкапсуляцию стилей.

Настройка и расширение

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

Для добавления плагинов в проект, нужно обновить конфигурацию stencil.config.ts, указав необходимые настройки. Например, можно использовать плагин для оптимизации стилей:

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

export const config: Config = {
  plugins: [
    optimizeCss(),
  ],
};

Заключение

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

Оглавление