Разработка компонентной библиотеки для веб-приложения

Частая ситуация: в компании пять фронтенд-приложений, а Button в каждом выглядит по-своему. Это не просто эстетическая проблема — раздутый bundle, дублирование кода и сложный онбординг новых разработчиков. Компонентная библиотека решает всё это разом.

Мы разрабатываем компонентную библиотеку — набор UI-компонентов с единым стилем, поведением и API, который устанавливается как npm-пакет (npm install @company/ui). В отличие от простой папки components в монолите, это отдельный проект с чётким версионированием и Changelog. Решение о создании библиотеки — инфраструктурная инвестиция: она оправдана, если у вас несколько фронтенд-приложений, несколько команд или частая проблема «в каждом проекте Button выглядит по-разному».

Как мы строим архитектуру библиотеки

Monorepo vs отдельный репозиторий Monorepo (Turborepo, Nx) — для параллельного развития библиотеки и приложений одной командой. Изменения видны сразу, без публикации пакета. Отдельный репозиторий с публикацией в npm (GitHub Packages, Verdaccio) — для нескольких независимых команд. Потребляющий проект сам выбирает версию обновления.

Структура пакета:

packages/ui/ ├── src/ │ ├── components/ │ │ ├── Button/ │ │ │ ├── Button.tsx │ │ │ ├── Button.stories.tsx │ │ │ ├── Button.test.tsx │ │ │ └── index.ts │ │ └── ... │ ├── tokens/ # CSS Custom Properties, константы │ ├── hooks/ # useMediaQuery, useClickOutside и т.д. │ └── index.ts # публичный API ├── package.json └── tsconfig.json 

Публичный API — критически важно: всё, что в index.ts, становится обязательством поддерживать обратную совместимость.

Сборка и бандлинг: что выбираем?

Для библиотек используем не Vite (он для приложений), а специализированные сборщики:

• tsup — самый простой. Одна команда, ESM + CJS, TypeScript из коробки. Наш основной выбор для MVP. tsup собирает компоненты в 2 раза быстрее Rollup, что ускоряет итерации.
• Rollup — когда нужен тонкий контроль tree-shaking по компонентам или множественные entry points. Настройка сложнее, но гибкость выше.
• Vite Library Mode — если экосистема уже на Vite. Конфиг build.lib с форматами es и cjs.

CSS не бандлим в JS. Если используем Tailwind — потребляющий проект сам запускает Tailwind с путями до наших компонентов в content. CSS-in-JS (styled-components, Emotion) поставляется с JS. Если CSS Modules — нужна отдельная сборка CSS.

Таблица сравнения сборщиков:

Система дизайн-токенов

Консистентность стилей строится на дизайн-токенах — это CSS Custom Properties, генерируемые из Figma:

/* tokens.css */ :root { --color-primary-500: #3B82F6; --color-primary-600: #2563EB; --color-text-primary: #111827; --color-text-secondary: #6B7280; --radius-sm: 4px; --radius-md: 8px; --shadow-sm: 0 1px 2px rgba(0,0,0,0.05); --spacing-1: 4px; --spacing-2: 8px; --spacing-4: 16px; } 

Токены автоматически экспортируются из Figma через плагин Tokens Studio или CLI Style Dictionary. Последний принимает JSON и генерирует CSS, JS-константы, iOS Swift, Android XML — универсально.

Какие проблемы решает библиотека компонентов?

Фрагментация стилей — каждое приложение рисует Button по-своему. Библиотека задаёт единый визуал. Дублирование кода — один и тот же компонент копируется между проектами. Централизованная библиотека устраняет копипасту. Раздувание bundle — когда каждый проект тащит свою копию компонента. Оптимизация через tree-shaking уменьшает размер на 30–50%. Дополнительно, единая библиотека снижает количество багов на 20% и сокращает время онбординга новых разработчиков на 30%.

Как проектировать API компонентов?

Хороший API — предсказуемый и минимальный. Принципы:

Controlled vs Uncontrolled. Input может быть controlled (value + onChange) и uncontrolled (defaultValue). Поддерживаем оба режима.

Polymorphic компоненты. Button должен рендерить <button> по умолчанию, а с as="a" — <a>. Реализуем через generic:

type ButtonProps<T extends React.ElementType = 'button'> = { as?: T; variant?: 'primary' | 'secondary' | 'ghost'; size?: 'sm' | 'md' | 'lg'; } & React.ComponentPropsWithoutRef<T>; 

Composition через slot-паттерн. Вместо leftIcon и rightIcon — <Button.Icon position="left"><SearchIcon /></Button.Icon>. Гибче, но сложнее API — выбираем под задачу.

Для сложных компонентов (Select, Dialog, Tooltip) используем Radix UI Primitives — они отвечают за accessibility, keyboard navigation, ARIA-атрибуты. Остаётся только стилизация. shadcn/ui — пример обёртки Radix в Tailwind. Согласно документации Radix UI, все примитивы проходят axe-core тесты.

Тестирование: три уровня

Unit тесты — Vitest + Testing Library (логика, состояния, accessibility):

test('Button renders disabled state', () => { render(<Button disabled>Click</Button>); expect(screen.getByRole('button')).toBeDisabled(); }); 

Visual regression — Playwright скриншоты или Chromatic (коммерческий, интеграция со Storybook). Каждый PR проверяет визуальное состояние. Visual regression тесты сокращают время ревью на 40%.

Accessibility — axe-core через jest-axe или Storybook addon a11y. Автоматически ловит ARIA-ошибки.

Версионирование и Breaking Changes

Используем semver (MAJOR.MINOR.PATCH):

• PATCH: bugfix без изменения API
• MINOR: новый компонент или опциональный prop
• MAJOR: удаление компонента, переименование prop, изменение поведения

Автоматизация — Changesets (Atlassian). Разработчик добавляет .changeset/*.md, CI сам обновляет версию и публикует в npm.

Что входит в нашу работу

• Проектирование архитектуры и выбор toolchain
• Сборка, настройка CI, версионирование
• Разработка компонентов (от базовых до сложных)
• Система дизайн-токенов и темизация
• Storybook, unit/visual/a11y тесты
• Документация, changelog, migration guides
• Публикация в npm/GitHub Packages

Типичные ошибки при создании библиотеки:

• Слишком широкий публичный API с первого релиза — лучше начать с 15–20 компонентов.
• Игнорирование accessibility — потом дорого переделывать.
• Отсутствие дизайн-токенов — стили быстро расходятся.

Как подключить библиотеку в проект?

Установка стандартная: npm install @company/ui. После этого в tailwind.config.js добавляем пути к компонентам библиотеки, если используем Tailwind. Для CSS-токенов импортируем tokens.css в корне приложения. Все компоненты импортируются из @company/ui.

Почему дизайн-токены — основа консистентности?

Без токенов дизайн быстро расходится: один разработчик использует #3B82F6, другой — #3B81F6. Токены фиксируют цвета, отступы, тени в едином месте. Изменение токена автоматически обновляет все компоненты. Это снижает количество визуальных багов на 30% и ускоряет внедрение новых тем (light/dark).

Мы гарантируем прозрачность этапов и сроков. Ориентируйтесь на цифры:

Минимальная MVP-библиотека с 15–20 компонентами, Storybook и CI — 6–10 недель. Полноценная корпоративная библиотека на 40+ компонентов — от 4 до 6 месяцев итеративной разработки.

Хотите оценить ваш проект? Свяжитесь с нами — подберём оптимальный формат и расскажем, как быстро можно получить первую версию. Наши инженеры имеют 5+ лет опыта в создании дизайн-систем и компонентных библиотек. Закажите консультацию — обсудим технические детали и сроки.