Storybook для Svelte

Storybook предоставляет мощную среду для разработки UI-компонентов, позволяя работать с ними изолированно от основного приложения. В SvelteKit интеграция Storybook осуществляется через официальные пакеты и настройки, адаптированные под Svelte.

Для начала необходимо установить зависимости:

npm install --save-dev @storybook/svelte @storybook/addon-essentials @storybook/addon-actions @storybook/addon-links

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

npx sb init

В main.js конфигурации указываются поддерживаемые фреймворки и пути к компонентам:

module.exports = {
  framework: '@storybook/svelte',
  stories: ['../src/lib/**/*.stories.@(js|ts|svelte)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-links',
    '@storybook/addon-actions'
  ],
};

Ключевой момент: для SvelteKit необходимо добавить поддержку Vite, чтобы Storybook корректно обрабатывал Svelte-файлы:

const { mergeConfig } = require('vite');
const svelteConfig = require('../svelte.config');

module.exports = {
  async viteFinal(config) {
    return mergeConfig(config, {
      ...svelteConfig,
    });
  },
};

Структура сториз

Файлы сториз в Svelte создаются рядом с компонентами и имеют расширение .stories.svelte или .stories.js/.ts. Основной принцип — описывать каждый компонент с несколькими состояниями (args).

Пример компонента Button:

<script>
  export let label = 'Кнопка';
  export let disabled = false;
</script>

<button disabled={disabled}>{label}</button>

Файл Button.stories.js:

import Button from './Button.svelte';

export default {
  title: 'UI/Button',
  component: Button,
  argTypes: {
    label: { control: 'text' },
    disabled: { control: 'boolean' },
  },
};

const Template = (args) => ({
  Component: Button,
  props: args,
});

export const Default = Template.bind({});
Default.args = {
  label: 'Нажми меня',
  disabled: false,
};

export const Disabled = Template.bind({});
Disabled.args = {
  label: 'Недоступно',
  disabled: true,
};

Важно: использование argTypes позволяет автоматически создавать контролы в панели Storybook и изменять пропсы в реальном времени.

Использование Addons

Storybook поддерживает расширения для улучшения разработки компонентов. Основные:

  • @storybook/addon-actions — отслеживание событий, таких как on:click в Svelte.
  • @storybook/addon-links — создание интерактивных переходов между сториз.
  • @storybook/addon-essentials — набор полезных инструментов, включая Docs, Controls, Viewport и Backgrounds.

Пример применения addon-actions:

<script>
  import { action } from '@storybook/addon-actions';
  export let label = 'Кнопка';
</script>

<button on:click={action('clicked')}>{label}</button>

Документация компонентов

Storybook позволяет создавать документацию в формате MDX, интегрированную с самими сториз. Это упрощает демонстрацию API компонентов и визуальных примеров.

Пример Button.stories.mdx:

import { Meta, Story, Canvas, ArgsTable } from '@storybook/addon-docs';
import Button from './Button.svelte';

<Meta title="UI/Button" component={Button} />

# Кнопка

<Canvas>
  <Story name="Default" args={{ label: 'Нажми меня' }} />
  <Story name="Disabled" args={{ label: 'Недоступно', disabled: true }} />
</Canvas>

<ArgsTable story="Default" />

Best Practices при работе со Svelte и Storybook

  1. Изоляция компонентов — каждый компонент должен быть независимым, без прямых ссылок на глобальные состояния приложения.
  2. Использование args и argTypes — позволяет легко тестировать различные состояния UI.
  3. MDX-документация — улучшает визуализацию API и делает компоненты более понятными для команды.
  4. Сториз как тесты — Storybook можно использовать совместно с @storybook/testing-library для написания визуальных тестов.
  5. Стилизация через Tailwind или CSS Modules — Storybook корректно обрабатывает все стили, если настроен Vite плагин для Svelte.

Интеграция с SvelteKit UI Libraries

При использовании сторонних UI-библиотек, таких как Svelte Material UI или Flowbite Svelte, Storybook позволяет:

  • демонстрировать кастомные темы и вариации компонентов,
  • создавать отдельные сториз для разных настроек темы,
  • отслеживать события и состояние компонентов через addon-actions.

Пример интеграции с Svelte Material UI:

import Button from 'svelte-material-ui/Button';

export default {
  title: 'Material/Button',
  component: Button,
};

export const Raised = {
  args: { raised: true, label: 'Поднятая кнопка' },
};

Storybook в SvelteKit превращается в полноценный инструмент для визуального тестирования и разработки UI, предоставляя мощные возможности для изоляции компонентов, документирования их API и проверки поведения в различных состояниях. Такой подход особенно полезен при работе с большими UI-библиотеками, где визуальное качество и консистентность компонентов критичны.

Оглавление