Storybook интеграция

Зачем использовать Storybook с Stencil?

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

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

Подготовка проекта

Для начала работы потребуется два основных компонента: сам Storybook и библиотека Stencil. Если проект еще не настроен, нужно выполнить несколько шагов:

  1. Установка Stencil: Stencil можно установить с помощью npm или yarn. В корне проекта выполняется следующая команда:

    npm init stencil

    Это создаст новый проект, настроенный для разработки веб-компонентов.

  2. Установка Storybook: Для интеграции с Stencil Storybook следует установить как dev-зависимость:

    npx sb init

    Эта команда инициализирует Storybook в проекте и создает нужные конфигурации для работы.

Настройка Storybook для работы с Stencil

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

  1. Установка необходимых зависимостей: Для того чтобы Storybook мог корректно отображать компоненты Stencil, необходимо установить дополнительные зависимости:

    npm install --save-dev @storybook/web-components @storybook/addon-docs

    Это добавит необходимые плагины и настроит Storybook для работы с веб-компонентами, включая те, которые созданы с помощью Stencil.

  2. Обновление конфигурации Storybook: В файле .storybook/main.js нужно указать, что Storybook будет использовать веб-компоненты для рендеринга. Пример конфигурации:

    module.exports = {
  stories: ['../src/components/**/*.stories.tsx'],
  addons: ['@storybook/addon-docs'],
  framework: '@storybook/web-components',
};

    В этой конфигурации мы указываем путь к файлам с историями (stories), а также включаем аддон для документации, который будет генерировать подробные описания компонентов.

  3. Создание истории (stories) для компонентов: Для каждого компонента необходимо создать файл с расширением .stories.tsx, в котором будут описаны различные состояния компонента. Пример истории для простого компонента my-button:

    import { html } from 'lit-html';
import { MyButton } from './my-button';

export default {
  title: 'UI/MyButton',
  component: 'my-button',
};

const Template = (args) => html`<my-button .label=${args.label}></my-button>`;

export const Default = Template.bind({});
Default.args = {
  label: 'Click me!',
};

    В этом примере мы создаем шаблон для компонента my-button, который принимает пропс label. Мы также указываем, что компонент должен отображаться с данным значением по умолчанию.

Работа с документацией в Storybook

Storybook предлагает встроенные инструменты для документирования компонентов, и Stencil поддерживает их благодаря аддону addon-docs. Для того чтобы компоненты автоматически отображались с документацией, достаточно добавить JSDoc комментарии к каждому элементу.

Пример использования JSDoc для компонента Stencil:

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

/**
 * Кнопка, которая отображает переданный текст
 */
@Component({
  tag: 'my-button',
  styleUrl: 'my-button.css',
  shadow: true,
})
export class MyButton {
  /**
   * Текст, который будет отображаться на кнопке
   */
  @Prop() label: string;

  render() {
    return <button>{this.label}</button>;
  }
}

С помощью JSDoc Storybook автоматически сгенерирует описание пропсов и их типов, что улучшает документацию и позволяет другим разработчикам легче понять, как использовать компоненты.

Проблемы и решения при интеграции

Несмотря на гибкость и простоту интеграции, могут возникнуть некоторые проблемы при работе с Stencil и Storybook.

  1. Отсутствие стилей: Иногда компоненты, созданные с помощью Stencil, не отображаются с нужными стилями в Storybook. Это может происходить из-за того, что Storybook не всегда корректно обрабатывает стили, добавленные в Shadow DOM. Чтобы решить эту проблему, можно использовать глобальные стили в файле preview.js:

    import '../src/global/styles.css';

    Это подключит глобальные стили, которые будут применяться ко всем компонентам внутри Storybook.

  2. Ошибки при загрузке компонентов: В случае, если компоненты не загружаются или не рендерятся, можно попробовать изменить конфигурацию Storybook или пересобрать проект. Важно следить за тем, чтобы компоненты экспортировались правильно и имели корректные типы.

  3. Поддержка TypeScript: Stencil использует TypeScript, а Storybook — JavaScript, что может вызывать проблемы с типами. Для решения этих проблем важно настроить Storybook на использование TypeScript, добавив в конфигурацию соответствующие настройки:

    module.exports = {
  typescript: {
    reactDocgen: 'react-docgen',
  },
};

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

Storybook также поддерживает тестирование компонентов с помощью различных аддонов, таких как @storybook/addon-actions, который позволяет отслеживать взаимодействие с компонентами, или @storybook/addon-essentials, который добавляет набор полезных инструментов для тестирования и анализа.

Для Stencil компонентов можно также интегрировать Storybook с тестовыми фреймворками, такими как Jest, чтобы проверять логику компонентов и их взаимодействие с пользователем. Таким образом, можно автоматизировать тестирование UI компонентов в реальном времени.

Заключение

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

Оглавление