Налаштування Storybook: жива документація UI-компонентів під ключ
Проблема: жива документація UI-компонентів без болю
Команда зростає, а компоненти множаться. Дизайнер пропонує новий варіант кнопки, розробник верстає, але старий варіант уже використовується в трьох місцях. Документація застаріла через тиждень. QA витрачає години на регресійне тестування кожної зміни. Ця ситуація знайома багатьом. Ми стикалися з цим не раз, тому пропонуємо налаштування Storybook — стандарту для живої документації та ізольованої розробки UI-компонентів, що підтримується командою Chromatic (офіційний сайт: https://storybook.js.org). Після впровадження Storybook та Chromatic візуальне регресійне тестування скорочує час регресу з кількох днів до 2 годин (у 6 разів швидше за ручне тестування), а охоплення компонентів сягає 95%. Storybook — це середовище, де кожен компонент описується Stories: окремими станами (кнопка за замовчуванням, disabled, loading, з іконкою). Розробник бачить усі стани одразу, дизайнер перевіряє без запуску застосунку, QA тестує кожен стан незалежно. Підтримує React, Vue, Angular, Svelte, Web Components — будь-який сучасний стек. За роки роботи ми впровадили Storybook у 35 проєктах: від стартапів до enterprise. Замовники суттєво скорочують бюджет на регресійне тестування (до $5000 економії на квартал у великих проєктах).
Як Storybook прискорює розробку компонентів?
Установка в наявний проєкт займає хвилину:
npx storybook@latest init
# Storybook визначить фреймворк автоматично
Після ініціалізації створюються папки .storybook/ (конфігурація) та stories/ (приклади). Ми переписуємо конфігурацію під ваш проєкт: підключаємо аддони, декоратори, глобальні стилі.
Базова конфігурація для React + Vite + TypeScript
Налаштування main.ts та preview.ts — ключовий етап. Від нього залежить, як аддони та сторі працюватимуть.
// .storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite'
const config: StorybookConfig = {
stories: ['../src/**/*.stories.@(ts|tsx)'],
addons: [
'@storybook/addon-essentials', // docs, controls, actions, viewport
'@storybook/addon-a11y', // перевірка доступності
'@storybook/addon-interactions', // тестування взаємодій
'@chromatic-com/storybook', // visual regression testing
],
framework: {
name: '@storybook/react-vite',
options: {},
},
staticDirs: ['../public'],
docs: {
autodocs: 'tag', // генерувати документацію для компонентів із тегом 'autodocs'
},
}
export default config
// .storybook/preview.ts
import type { Preview } from '@storybook/react'
import '../src/styles/globals.css' // підключити глобальні стилі (Tailwind, якщо використовується)
const preview: Preview = {
parameters: {
controls: {
matchers: {
color: /(background|color)$/i,
date: /Date$/i,
},
},
viewport: {
defaultViewport: 'responsive',
},
backgrounds: {
default: 'light',
values: [
{ name: 'light', value: '#ffffff' },
{ name: 'dark', value: '#0f172a' },
{ name: 'gray', value: '#f8fafc' },
],
},
},
decorators: [
(Story) => (
<ThemeProvider>
<Story />
</ThemeProvider>
),
],
}
export default preview
Цього достатньо. Storybook через Vite підхопить конфігурацію Tailwind автоматично, якщо вона є в проєкті.
Написання Stories у форматі CSF 3
Component Story Format 3 (CSF 3) — актуальний стандарт. Приклад для кнопки:
// src/components/Button/Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react'
import { fn } from '@storybook/test'
import { Button } from './Button'
const meta = {
title: 'UI/Button',
component: Button,
tags: ['autodocs'], // автоматично генерувати сторінку документації
parameters: {
layout: 'centered', // 'centered' | 'fullscreen' | 'padded'
},
argTypes: {
variant: {
control: 'select',
options: ['primary', 'secondary', 'destructive', 'ghost'],
},
size: {
control: 'radio',
options: ['sm', 'md', 'lg'],
},
disabled: { control: 'boolean' },
loading: { control: 'boolean' },
},
args: {
onClick: fn(), // автоматично логується в панелі Actions
},
} satisfies Meta<typeof Button>
export default meta
type Story = StoryObj<typeof meta>
export const Default: Story = {
args: {
children: 'Натиснути',
variant: 'primary',
size: 'md',
},
}
export const Destructive: Story = {
args: {
children: 'Видалити',
variant: 'destructive',
size: 'md',
},
}
export const Loading: Story = {
args: {
children: 'Зберігається...',
loading: true,
variant: 'primary',
},
}
export const AllVariants: Story = {
render: () => (
<div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
{(['primary', 'secondary', 'destructive', 'ghost'] as const).map((v) => (
<Button key={v} variant={v}>{v}</Button>
))}
</div>
),
}
Для складних компонентів, наприклад таблиці з даними, можна додати тести взаємодій за допомогою play-функції:
// src/components/DataTable/DataTable.stories.tsx
import type { Meta, StoryObj } from '@storybook/react'
import { expect, userEvent, within } from '@storybook/test'
import { DataTable } from './DataTable'
import { columns, mockData } from './__fixtures__/data'
const meta = {
title: 'Data/DataTable',
component: DataTable,
tags: ['autodocs'],
} satisfies Meta<typeof DataTable>
export default meta
type Story = StoryObj<typeof meta>
export const Empty: Story = {
args: { columns, data: [] },
}
export const WithData: Story = {
args: { columns, data: mockData.slice(0, 5) },
}
export const Sortable: Story = {
args: { columns, data: mockData, sortable: true },
play: async ({ canvasElement }) => {
const canvas = within(canvasElement)
const nameHeader = canvas.getByText('Ім\'я')
await userEvent.click(nameHeader)
const firstRow = canvas.getAllByRole('row')[1]
await expect(firstRow).toBeInTheDocument()
},
}
Реальний кейс: Angular-проєкт із 50+ компонентами
Один із наших замовників розробляв корпоративний портал на Angular. Документація компонентів була відсутня, QA витрачав 3 дні на регрес кожного релізу. Ми за тиждень налаштували Storybook, написали 60 stories для 15 ключових компонентів і підключили Chromatic. У перший місяць QA виявив 17 візуальних розбіжностей, які раніше пропускали. Замовник скоротив час регресу до 4 годин (у 18 разів швидше) і заощадив близько $5000 на квартал. Зараз команда додає нові компоненти в Storybook самостійно.
Порівняння Storybook і ручної документації
| Критерій | Ручна документація | Storybook |
|---|---|---|
| Актуальність | Потребує постійного оновлення | Завжди синхронізована з кодом |
| Тестування змін | Вручну, через скріншоти | Автоматичне (візуальний регрес) |
| Зручність для QA | Потрібно бігати по розділах | Всі стани на одній сторінці |
| Інтеграція з тестами | Немає | addon-interactions + play-функції |
Жива документація UI-компонентів: що ви отримаєте в результаті?
- Жива документація всіх UI-компонентів із можливістю інтерактивного перегляду
- Автоматичні тести доступності (a11y) за допомогою addon-a11y
- Візуальне регресійне тестування через Chromatic — кожна зміна контролюється
- Гайд із додавання нових компонентів у Storybook для розробників
- Деплой статичної збірки на ваш хостинг (GitHub Pages, Netlify, ваш сервер)
- Навчання команди — 2-годинний воркшоп із роботи з Storybook
Як інтегрувати Storybook із Chromatic?
Для візуального регресійного тестування ми підключаємо Chromatic. Він автоматично робить скріншоти всіх Stories при кожному коміті та порівнює з еталоном. Якщо є розбіжності — надсилає сповіщення в Slack або e-mail. Налаштування займає близько години: реєструємо проєкт, додаємо токен у CI та запускаємо збірку.
Типові проблеми при впровадженні Storybook
| Проблема | Рішення | Як ми допомагаємо |
|---|---|---|
| Конфлікт глобальних стилів | Ізолювати стилі в preview.ts | Налаштовуємо декоратори та імпорти |
| Повільна збірка | Використовувати Vite замість Webpack | Перемикаємо бандлер, оптимізуємо |
| Відсутність тестів | Підключаємо addon-interactions | Пишемо play-функції для тестів |
| Незрозуміло, як писати Stories | CSF 3 документація | Складаємо гайд і приклади |
Досвід і результати
Ми — команда з більш ніж 10-річним досвідом у frontend-розробці, 5+ років на ринку. За багаторічну практику впровадили Storybook у 35+ проєктах: від стартапів до enterprise із Angular, React, Vue та Svelte. Наші клієнти відзначають скорочення часу QA на 40% (у 1.67 раза) і збільшення швидкості розробки компонентів на 25%. Гарантуємо результат — документація буде живою та завжди актуальною. Зв'яжіться з нами для аудиту ваших компонентів і отримайте комерційну пропозицію з точними термінами.
Що входить у роботу
- Аналіз вашого стеку та компонентів. Визначаємо, які аддони потрібні.
- Установка та конфігурація Storybook з усіма залежностями (Vite, TypeScript, CSS-фреймворк).
- Написання Stories для наявних компонентів із контролами та діями.
- Налаштування автоматичної документації через
autodocsта MDX-сторінки. - Підключення візуального регресійного тестування (Chromatic).
- Деплой статичної збірки на хостинг (GitHub Pages, Netlify, ваш сервер).
- Навчання команди — 2-годинний воркшоп із практикою.
- Документація з інструкціями та доступ до Storybook.
- Підтримка протягом місяця після впровадження.
Терміни та бюджет
Терміни розраховуються індивідуально під ваш проєкт. Базове налаштування займає від 0,5 дня, написання Stories для наявних компонентів — 1–3 години на кожні 10 компонентів. Точну оцінку надаємо після аудиту вашої кодової бази. Замовте налаштування Storybook під ключ — напишіть нам, і ми зв'яжемося з вами протягом дня.