Что такое Storybook?

Storybook — это интерактивная библиотека компонентов. Каждый элемент интерфейса существует независимо от остального приложения: его можно протестировать, задокументировать и показать коллеге — всё без запуска основного приложения.

Представьте проект как огромную библиотеку. Без Storybook — неструктурированность: книги (компоненты) разбросаны, найти нужное невозможно. Со Storybook — каждая «книга» с чёткой классификацией: обложкой (визуализацией) и аннотацией (документацией).

Можно сравнить с выбором фильма: вы смотрите трейлер, читаете описание — Storybook делает то же самое, но для компонентов.

Преимущества Storybook:

• изоляция — компоненты создаются и тестируются вне основного приложения,
• документация — генерация на основе кода, автоматическое обновление,
• синхронность — вся команда работает с одними и теми же историями,
• ускорение — быстрый фидбек, меньше багов, легкий онбординг,
• гибкость — поддержка React, Vue, Angular и других стеков,
• демонстрация — возможность показать компонент с нужными пропсами по ссылке.

Storybook используется в:

• Airbnb — управление React-библиотекой,
• Google — создание дизайн-систем,
• Microsoft — поддержка веб-проектов,
• Uber и Netflix — изолированная разработка и тестирование UI.

источник: сайт Storybook

Как устроен Storybook

1) Stories

Файлы .stories.tsx с примерами использования компонентов в разных состояниях (в Next.js мы используем TypeScript, поэтому расширение .tsx).

Stories описывают компоненты:

• title — путь / заголовок в интерфейсе,
• argtypes — описание пропсов (типы, опции, контроль значений и т. д.).

Здесь же можно описать, какие «действия» могут происходить с компонентом (например, клик по кнопке, отправка формы). На картинке ниже представлены две истории одного компонента.

Каждая Story — это компонент с определенными пропсами и состояниями.

2) UI состоит из следующих разделов:

• навигация по компонентам,
• панель Controls для управления пропсами (особенно полезно для тестирования различных состояний компонента),
• превью — изолированная среда (iframe).

3) Архитектура

Storybook имеет модульную архитектуру, которая делает его гибким и расширяемым.

1) Менеджер — это «мозг» Storybook. Он отвечает за:

• UI: навигацию между Stories, панелью управления и настройками,
• отображение: управление компонентами и их документацией,
• интеграцию с аддонами: подключение дополнительных функций.

2) Превью — это «движок», который:

• рендерит компоненты: отображает их в изолированной среде (iframe),
• обеспечивает изоляцию: компоненты доступны независимо от основного приложения,
• поддерживает интерактивность: возможность взаимодействовать с компонентами в реальном времени.

3) Аддоны — дополнительные модули, расширяющие функциональность Storybook. Например:

• Docs: автоматическая генерация документации для компонентов,
• Controls: интерактивное изменение пропсов компонентов,
• Actions: логирование событий (например, клики, ввод данных),
• Viewport: тестирование компонентов на разных экранах.

Как внедрить Storybook за 5 шагов

1) Установка в проект как зависимость.

2) Настройка конфигов:

• main.ts — отвечает за сборку, подключение аддонов, указание того, где искать Stories и т. д.,
• preview.tsx — отвечает за глобальные настройки рендеринга компонентов.

3) Создание Stories: описание компонентов во всех состояниях.

4) Запуск как у локального веб-сервера, на котором разрабатывается сайт.

5) Интерактивное взаимодействие с UI: ссылка на конкретную историю для быстрого фидбэка и проверки.

Интеграция с CI/CD

CI/CD позволяет автоматизировать процессы сборки, тестирования и публикации компонентов, обеспечивая стабильность, согласованность и актуальность пользовательского интерфейса при каждом изменении кода и на всех этапах разработки. Также это возможность убедиться, что компоненты работают корректно в изолированной среде.

Пример CI/CD-пайплайна для Storybook

1) Интеграция с CI (Continuous Integration):

• настройка CI-системы (GitHub Actions, GitLab CI, Jenkins, CircleCI и т. д.) для автоматического запуска сборки и тестов Storybook при каждом push или pull request.

Добавление шагов в CI-workflow для:

• установки зависимостей (npm install или yarn install),
• сборки Storybook (npm run build-storybook или yarn build-storybook).

2) Визуальные регрессионные тесты (Visual Testing) с помощью Chromatic или Loki:

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

3) Публикация Storybook:

• настройка CI для автоматической публикации собранного Storybook (папки storybook-static или dist) на хостинг (например, GitHub Pages, Netlify, Vercel, AWS S3) после успешной сборки и прохождения всех тестов,
• автоматическое обновление документации при каждом изменении.

4) Автоматическое развертывание:

• интеграция с системами деплоя для автоматического отражения изменений в компонентах в продакшн после прохождения всех тестов.

Интеграция с CI/CD — это не просто автоматизация, а системный подход к качеству компонентов.

Визуальное тестирование c Loki

Loki — это инструмент визуального тестирования, который интегрируется с Storybook. Он позволяет находить визуальные регрессии, сравнивая скриншоты компонентов.

Как это работает?

1) Генерация эталонных скриншотов.

2) Сравнение с эталонными скриншотами после изменений.

3) Интеграция с CI/CD — Loki помогает заранее отлавливать UI-баги, автоматизировать тестирование и снижать риски при релизах.

Возможные сложности

Технические:

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

Функциональные:

• используются моки и стабы для API и бэкенда, что может не отражать реальное поведение компонентов,
• работа с контекстом (Redux, Context API и др.) требует настройки декораторов,
• не покрывает бизнес-логику и сложные сценарии — нужны дополнительные инструменты и стратегии тестирования,
• для небольших проектов может оказаться «перегруженным».

Организационные:

• истории быстро устаревают, требуют поддержки при любом изменении компонентов,
• при масштабировании нужна четкая структура и навигация внутри Storybook,
• Storybook завязан на конкретный UI-фреймворк (React, Vue, Angular и т. д.) — при смене придётся переписывать истории,
• есть кривая обучения — новым разработчикам может понадобиться время на освоение.

Как минимизировать трудности:

• продумать архитектуру заранее,
• автоматизировать сборку и тестирование для поддержания в актуальном состоянии (используя скрипты и инструменты),
• ввести единые правила написания Stories и документирования компонентов,
• использовать аддоны для упрощения тестирования и документации,
• регулярно ревьюить истории и компоненты на соответствие текущим стандартам и требованиям,
• внедрять поэтапно: начинать с внедрения для небольшого количества ключевых компонентов, а затем постепенно расширять использование.

Примеры

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

Пример 1: Storybook Design System (SDS)

Внутренняя команда Storybook использует Storybook для собственной дизайн-системы (SDS). Этот подход решает проблемы повторной вставки одних и тех же компонентов в несколько проектов, а также упрощает создание пользовательских интерфейсов с использованием шаблонов дизайна Storybook.

Работает по следующему принципу:

• SDS можно установить как зависимость и использовать в качестве библиотеки компонентов,
• каждый компонент доступен через Storybook-интерфейс в виде интерактивной истории.

Из предложенного списка можно выбрать компонент, например AvatarList (см. пример ниже).

1. Слева — навигация, UI-компоненты, небольшое интро о SDS и даже цветовая палитра сайта.
2. Справа вверху — инструменты для работы с отображением UI-компонентов. Можно заменить фон, на котором рендерится компонент, наложить сетку макета, выбрать размер экрана, вынести компонент на отдельную страницу и тестировать изолированно, а также добавить дополнительную функциональность с помощью аддонов.
3. Справа посередине — визуальное представление компонента.
4. Справа внизу — область для взаимодействия с пропсами компонентов: можно менять пропсы, и компонент будет ререндериться на лету. Есть вкладка Actions, где можно посмотреть, как логируются те или иные события, вкладка с кодом истории, а также вкладка с доступностью компонентов, в которой отображаются предупреждения и ошибки, которые рекомендуется устранить (например, недостаточно различимый цвет текста у кнопки).

Есть возможность переключаться между историями (например, Basic / Loading) и увидеть, как компонент выглядит в состоянии загрузки. А если мы активируем в настройках Storybook автоматическую документацию, то будет доступна вкладка Docs внутри компонента:

Пример 2: NEO — проект Only

Интеграция прошла стандартно (проект построен на фреймворке Next.js, с которым Storybook совместим), но потребовалась донастройка: плагин postcss-variable-compress некорректно обрабатывается в Storybook, и глобальные переменные перезаписываются. В результате получалось что-то вроде этого:

Отключение плагина → всё заработало.

Благодаря большому количеству разобранных кейсов и активному сообществу, процесс интеграции, состоящий из: настройки конфигурации, описания Stories для компонентов, добавления контекстов и декораторов (например, стейт-менеджер Recoil или NextIntlClientProvider для интернационализации), не вызвал трудностей.

Теперь все UI-компоненты:

• собраны централизованно,
• задокументированы,
• доступны для тестирования и фидбэка.

Storybook особенно полезен для визуальных компонентов (например, компонент баннера).

Можно изменять и тестировать компоненты в интерактивном режиме, а также экспериментировать с пропсами, сразу видя, как они влияют на отображение и поведение компонента.

Вывод

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

На проекте Only — NEO Storybook стал незаменимым помощником для всей команды. Скорее всего, станет таким и на вашем.