> ## Documentation Index
> Fetch the complete documentation index at: https://ui8kit.buildy.tw/llms.txt
> Use this file to discover all available pages before exploring further.

# Система сборки

> Конвейер сборки UI8Kit Core - компиляция TypeScript, модульное связывание, извлечение CVA и настройка распространения NPM

# Система сборки

## Цель и область применения

Этот документ описывает систему сборки, которая компилирует исходный код TypeScript в распространяемые JavaScript-модули для публикации в NPM. Он объясняет процесс компиляции, скрипты сборки, конфигурацию TypeScript, структуру выходных данных и настройку распространения.

Информацию о структуре пакета и экспорте модулей см. в разделе [Структура пакета](#3.5). Подробности о системе реестра компонентов, которая обеспечивает установку отдельных компонентов, см. в разделе [Реестр компонентов](#3.7). Для деталей, специфичных для TypeScript, включая псевдонимы путей и генерацию типов, см. [Конфигурация TypeScript](#3.8).

***

## Обзор конвейера сборки

Система сборки преобразует исходный код TypeScript в `src/` в JavaScript-модули ES2022 с файлами объявлений в `dist/`, а также в генерируемые артефакты, которые поддерживают Tailwind CSS и инструменты сборки.

```
Распространение

Артефакты сборки

Скрипты сборки

Исходный код

bun scripts/cva-extractor.ts

генерирует

выдает

выдает

bunx buildy-ui scan

сканирует

сканирует

генерирует

публикует

safelist для
очистки Tailwind

src/core/ui/
Примитивы: Block, Box, Grid и т.д.

src/core/variants/
Определения вариантов CVA

src/components/ui/
Составные компоненты

src/layouts/
Шаблоны макетов

src/index.ts
Главная точка входа

scripts/cva-extractor.ts
Извлекает 618 CSS-классов

tsc -p tsconfig.json
Компилятор TypeScript

eslint src --ext .ts,.tsx
Проверка качества кода

buildy-ui scan
Генерация реестра

src/lib/core-classes.json
Белый список из 618 классов

dist/index.js
Вывод модуля ES2022

dist/index.d.ts
Объявления TypeScript

src/registry.json
Метаданные компонентов

Пакет NPM
@ui8kit/Unsupported markdown: link

Файлы пакета:
dist/**, README.md, LICENSE

Приложения
потребителей
```

**Источники:** [package.json21-28](https://github.com/ui8kit/core/blob/2afe2195/package.json#L21-L28) [tsconfig.json1-26](https://github.com/ui8kit/core/blob/2afe2195/tsconfig.json#L1-L26) [scripts/cva-extractor.ts1-339](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L1-L339)

***

## Команды сборки

Система сборки предоставляет несколько npm-скриптов, определенных в `package.json`, для различных аспектов сборки и рабочего процесса разработки.

### Основные команды сборки

| Команда | Скрипт | Назначение |
| - | - | - |
| `npm run build` | `tsc -p tsconfig.json` | Компиляция TypeScript в JavaScript с файлами объявлений |
| `npm run type-check` | `tsc --noEmit` | Проверка типов без генерации файлов |
| `npm run lint` | `eslint src --ext .ts,.tsx` | Проверка качества и стиля кода |
| `npm run lint:fix` | `eslint src --ext .ts,.tsx --fix` | Автоматическое исправление проблем линтинга |

### Команды инструментов

| Команда | Скрипт | Назначение |
| - | - | - |
| `npm run scan` | `bunx buildy-ui@latest scan` | Генерация метаданных реестра компонентов |
| `npm run build:r` | `bunx buildy-ui@latest build` | Сборка пакета реестра |
| `npm run publish` | `cd packages/registry && npm version patch && npm publish` | Публикация реестра в NPM |

### Ручные скрипты сборки

| Скрипт | Команда | Назначение |
| - | - | - |
| Извлечение CVA | `bun scripts/cva-extractor.ts` | Извлечение CSS-классов из определений вариантов |

**Источники:** [package.json21-28](https://github.com/ui8kit/core/blob/2afe2195/package.json#L21-L28)

***

## Процесс компиляции TypeScript

Компилятор TypeScript (`tsc`) преобразует исходные файлы из `src/` в скомпилированные JavaScript-модули и файлы объявлений в `dist/`, используя конфигурацию, определенную в `tsconfig.json`.

```
Выходные данные

Процесс компиляции

Настройки компилятора

Входные данные компиляции

tsconfig.json
Конфигурация компилятора

src//*.ts
src//*.tsx
Исходный код TypeScript

target: ES2022
Современные возможности JavaScript

module: ES2022
moduleResolution: Bundler

jsx: react-jsx
Преобразование JSX React 18+

Псевдонимы путей:
@/* → ./src/*

Проверка типов
strict: true

Преобразование JSX
react-jsx runtime

Генерация объявлений
declaration: true

Генерация файлов
outDir: ./dist

dist/index.js
Модули ES2022

dist/index.d.ts
Объявления типов

dist//*.js
dist//*.d.ts
Скомпилированные подмодули
```

### Конфигурация компиляции

Компилятор TypeScript настроен в [tsconfig.json1-26](https://github.com/ui8kit/core/blob/2afe2195/tsconfig.json#L1-L26) со следующими ключевыми параметрами:

| Параметр | Значение | Назначение |
| - | - | - |
| `target` | `ES2022` | Вывод современного JavaScript с возможностями ES2022 |
| `module` | `ES2022` | Использование ES-модулей (синтаксис import/export) |
| `moduleResolution` | `Bundler` | Разрешение модулей для современных сборщиков |
| `rootDir` | `src` | Корневой каталог исходного кода |
| `outDir` | `./dist` | Каталог скомпилированного вывода |
| `declaration` | `true` | Генерация файлов объявлений типов `.d.ts` |
| `declarationDir` | `./dist` | Расположение вывода для объявлений |
| `jsx` | `react-jsx` | Использование автоматического преобразования JSX React 18+ |
| `strict` | `true` | Включение всех опций строгой проверки типов |

### Псевдонимы путей

Компилятор разрешает псевдонимы путей во время компиляции:

```
// Конфигурация псевдонимов путей
{
  "@/*": ["./src/*"],              // Сопоставляет @/ с src/
  "@ui8kit/core": ["./src/index"]  // Сопоставляет импорт пакета с src/index
}
```

Эти псевдонимы используются в исходном коде, но разрешаются в относительные пути в скомпилированном выводе.

**Источники:** [tsconfig.json4-24](https://github.com/ui8kit/core/blob/2afe2195/tsconfig.json#L4-L24) Диаграмма 2 из высокоуровневой архитектуры

***

## Структура вывода

Процесс компиляции генерирует структурированный вывод в каталоге `dist/`, который отражает структуру исходного кода.

### Схема каталога распространения

```
Каталог вывода dist/

Поддерживающие модули

Модули макетов

Модули компонентов

Основные модули

импортирует

импортирует

импортирует

импортирует

импортирует

импортирует

dist/themes/
Система тем

dist/index.js
Главный модуль точки входа

dist/core/ui/
Скомпилированные примитивные компоненты

dist/core/variants/
Определения вариантов CVA

dist/components/ui/
Составные компоненты

dist/layouts/
Шаблоны макетов

dist/hooks/
React-хуки

dist/ui/
Экспорты UI-компонентов

dist/core/utils/
Утилитарные функции

dist/index.d.ts
Главные объявления типов
```

### Структура точки входа

Главная точка входа в [src/index.ts1-32](https://github.com/ui8kit/core/blob/2afe2195/src/index.ts#L1-L32) определяет публичный API через серию экспортов:

```
// Структура экспорта из src/index.ts
export * from './core/variants';      // Определения вариантов
export * from './core/utils';         // Утилитарные функции

// Базовые примитивы с префиксом Base
export {
  Block as BaseBlock,
  Box as BaseBox,
  // ... и т.д.
} from './core/ui';

// Составные компоненты (основные экспорты)
export * from './ui';                 // Button, Card и т.д.

// Компоненты макетов
export * from './layouts';            // DashLayout, LayoutBlock и т.д.

// Система тем
export * from './themes';             // ThemeProvider, useTheme

// React-хуки
export * from './hooks';
```

Эта структура сохраняется в скомпилированном `dist/index.js` со всеми импортами, разрешенными в относительные пути.

### Генерируемые типы файлов

| Тип файла | Расширение | Назначение |
| - | - | - |
| JavaScript-модули | `.js` | Исполняемый код ES2022 |
| Объявления типов | `.d.ts` | Информация о типах TypeScript |
| Карты объявлений | `.d.ts.map` | Сопоставление источников для объявлений |

**Источники:** [src/index.ts1-32](https://github.com/ui8kit/core/blob/2afe2195/src/index.ts#L1-L32) [tsconfig.json13-19](https://github.com/ui8kit/core/blob/2afe2195/tsconfig.json#L13-L19) [package.json31-37](https://github.com/ui8kit/core/blob/2afe2195/package.json#L31-L37)

***

## Конфигурация распространения

Пакет настроен для распространения через NPM с помощью параметров в `package.json`, которые определяют, как скомпилированный код предоставляется потребителям.

### Конфигурация экспорта модулей

Пакет определяет свои экспорты, используя современное поле `exports`:

```
{
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  }
}
```

Эта конфигурация:

* **`main`**: Точка входа по умолчанию для CommonJS и старых инструментов
* **`types`**: Расположение файла объявлений TypeScript
* **`exports["."]`**: Современные условные экспорты для ESM и типов

### Файлы распространения пакета

Поле `files` в [package.json39-43](https://github.com/ui8kit/core/blob/2afe2195/package.json#L39-L43) указывает, какие файлы включены в опубликованный пакет:

```
{
  "files": [
    "dist/**/*",      // Весь скомпилированный вывод
    "README.md",      // Документация
    "LICENSE"         // Файл лицензии
  ]
}
```

### Метаданные пакета

| Поле | Значение | Назначение |
| - | - | - |
| `name` | `@ui8kit/core` | Имя пакета NPM |
| `version` | `0.1.8` | Номер семантической версии |
| `type` | `module` | Объявляет пакет как ESM |
| `sideEffects` | `false` | Включает оптимизацию tree-shaking |
| `publishConfig.access` | `public` | Разрешает публичный доступ NPM |

**Источники:** [package.json1-43](https://github.com/ui8kit/core/blob/2afe2195/package.json#L1-L43) [package.json67-69](https://github.com/ui8kit/core/blob/2afe2195/package.json#L67-L69)

***

## Инструменты времени сборки

Система сборки включает специализированные скрипты, которые выполняются во время разработки для генерации артефактов, необходимых для системы времени выполнения и приложений потребителей.

### Экстрактор классов CVA

Скрипт [scripts/cva-extractor.ts1-339](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L1-L339) анализирует определения вариантов для извлечения CSS-классов, используемых библиотекой.

```
Процесс экстрактора CVA

Извлечение классов

Базовые классы
Строки первого аргумента

Вход:
src/core/variants/**/*.ts
Все файлы определений вариантов

Babel Parser
Парсинг AST TypeScript

Обход AST
Поиск вызовов cva()

Классы вариантов
Свойства объектов

Составные варианты
Вложенные объекты

Дедупликация
Уникальность на основе Set

Выход:
src/lib/core-classes.json
618 уникальных классов
```

### Реализация экстрактора

Класс `SimpleCVAExtractor` обрабатывает файлы вариантов:

1. **Обнаружение файлов**: Рекурсивно сканирует [src/core/variants/](https://github.com/ui8kit/core/blob/2afe2195/src/core/variants/) для файлов `.ts` и `.tsx`

2. **Парсинг AST**: Использует `@babel/parser` для парсинга синтаксиса TypeScript

3. **Обнаружение CVA**: Находит вызовы функции `cva()` через обход AST

4. **Извлечение классов**: Извлекает все строковые литералы из:

   * Базовых классов (первый аргумент)
   * Объектов вариантов (свойства второго аргумента)
   * Вложенных определений вариантов

5. **Дедупликация**: Использует `Set<string>` для обеспечения уникальности

6. **Генерация вывода**: Записывает JSON-массив из 618 классов

### Генерируемый белый список классов

Экстрактор создает [src/lib/core-classes.json1-624](https://github.com/ui8kit/core/blob/2afe2195/src/lib/core-classes.json#L1-L624) со следующей структурой:

```
{
  "classes": [
    "absolute",
    "accent-auto",
    // ... еще 616 классов
    "z-auto"
  ],
  "count": 618,
  "timestamp": "2025-10-29T12:17:54.882Z"
}
```

Этот белый список служит двум целям:

1. **Safelist Tailwind**: Предотвращает удаление классов, генерируемых вариантами, при очистке CSS
2. **Конфигурация tw-merge**: Обеспечивает безопасное слияние классов, генерируемых вариантами

### Сканер реестра компонентов

Команда `buildy-ui scan` генерирует [src/registry.json](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json) анализируя файлы компонентов на предмет метаданных, используемых системой установки отдельных компонентов. Подробности см. в разделе [Реестр компонентов](#3.7).

**Источники:** [scripts/cva-extractor.ts11-279](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L11-L279) [src/lib/core-classes.json1-624](https://github.com/ui8kit/core/blob/2afe2195/src/lib/core-classes.json#L1-L624) Диаграмма 2 и Диаграмма 5 из высокоуровневой архитектуры

***

## Артефакты сборки

Процесс сборки генерирует несколько зафиксированных артефактов, которые соединяют системы времени сборки и времени выполнения.

### Сводка артефактов

```
Использование во время выполнения

Зафиксированные артефакты

Генерация во время сборки

создает

создает

создает

npm run build

bun scripts/cva-extractor.ts

npm run scan

dist/
Скомпилированный JS + типы
Генерируется tsc

src/lib/core-classes.json
618 CSS-классов
Генерируется экстрактором CVA

src/registry.json
Метаданные компонентов
Генерируется buildy-ui

npm install @ui8kit/core
Устанавливает вывод dist/

Consumer tailwind.config.js
Использует core-classes.json

npx buildy-ui add button
Использует registry.json
```

### Детали артефактов

| Артефакт | Расположение | Генерируется | Назначение | Зафиксирован |
| - | - | - | - | - |
| Скомпилированные модули | `dist/**/*.js` | `tsc` | Код времени выполнения для пакета NPM | Да |
| Объявления типов | `dist/**/*.d.ts` | `tsc` | Информация о типах TypeScript | Да |
| Белый список CSS-классов | `src/lib/core-classes.json` | `cva-extractor.ts` | Конфигурация safelist Tailwind | Да |
| Реестр компонентов | `src/registry.json` | `buildy-ui scan` | Установка отдельных компонентов | Да |

### Почему артефакты зафиксированы

Артефакты сборки зафиксированы в репозитории (в отличие от типичных проектов Node.js) по нескольким причинам:

1. **Готовность к NPM**: Каталог `dist/` может быть опубликован напрямую без необходимости выполнения шагов сборки потребителями
2. **Совместимость с подмодулями**: Установки подмодулей Git могут использовать скомпилированный вывод без инструментов сборки
3. **Стабильность белого списка**: Файл `core-classes.json` служит версионированным контрактом для конфигураций Tailwind
4. **Доступность реестра**: `registry.json` обеспечивает установку отдельных компонентов без необходимости полной установки пакета

**Источники:** [package.json39-43](https://github.com/ui8kit/core/blob/2afe2195/package.json#L39-L43) [src/lib/core-classes.json1-624](https://github.com/ui8kit/core/blob/2afe2195/src/lib/core-classes.json#L1-L624) Диаграмма 5 из высокоуровневой архитектуры

***

## Пример рабочего процесса сборки

Типичный рабочий процесс разработки включает последовательное выполнение команд сборки:

### Полная последовательность сборки

```
# 1. Извлечение классов CVA (обновляет src/lib/core-classes.json)
bun scripts/cva-extractor.ts

# 2. Проверка типов исходного кода
npm run type-check

# 3. Линтинг исходного кода
npm run lint

# 4. Компиляция TypeScript (генерирует dist/)
npm run build

# 5. Генерация реестра компонентов
npm run scan

# 6. Публикация в NPM (из packages/registry/)
npm run publish
```

### Сборка для разработки

Для итеративной разработки выполните минимальную сборку:

```
# Быстрая сборка для тестирования
npm run build

# Или просто проверка типов без генерации
npm run type-check
```

### Непрерывная интеграция

Конвейер CI/CD обычно выполняет:

```
npm run lint          # Качество кода
npm run type-check    # Безопасность типов
npm run build         # Компиляция
```

**Источники:** [package.json21-28](https://github.com/ui8kit/core/blob/2afe2195/package.json#L21-L28)

***

## Зависимости и требования

Система сборки требует определенных инструментов и зависимостей для корректной работы.

### Зависимости времени сборки

| Зависимость | Версия | Назначение |
| - | - | - |
| `typescript` | `^5.6.3` | Компилятор TypeScript |
| `@babel/parser` | `^7.28.4` | Парсинг AST для извлечения CVA |
| `@babel/traverse` | `^7.28.4` | Обход AST для извлечения CVA |
| `bun-types` | `^1.1.29` | Определения типов для среды выполнения Bun |

### Зависимости времени выполнения

Они включены в пакет:

| Зависимость | Версия | Назначение |
| - | - | - |
| `class-variance-authority` | `^0.7.1` | Движок вариантов CVA |
| `clsx` | `^2.1.1` | Утилита для имен классов |
| `tailwind-merge` | `^3.3.1` | Слияние имен классов |
| `lucide-react` | `^0.525.0` | Компоненты иконок |
| `react-resizable-panels` | `^3.0.6` | Изменение размера макетов |

### Одноранговые зависимости

Приложения-потребители должны предоставить:

| Зависимость | Диапазон версий | Назначение |
| - | - | - |
| `react` | `^18.0.0 \|\| ^19.0.0` | Среда выполнения React |
| `react-dom` | `^18.0.0 \|\| ^19.0.0` | Рендерер React DOM |

**Источники:** [package.json48-66](https://github.com/ui8kit/core/blob/2afe2195/package.json#L48-L66)

***

## Решение проблем сборки

### Распространенные проблемы сборки

| Проблема | Причина | Решение |
| - | - | - |
| `tsc` не найден | TypeScript не установлен | Запустите `npm install` для установки dev-зависимостей |
| Ошибки типов во время сборки | Строгая проверка типов | Исправьте ошибки типов или временно отключите с помощью `npm run type-check` |
| Отсутствует вывод `dist/` | Сборка не выполнена | Явно запустите `npm run build` |
| Классы CVA не найдены | Белый список не сгенерирован | Запустите `bun scripts/cva-extractor.ts` |
| Реестр не синхронизирован | Компоненты изменились | Запустите `npm run scan` для повторной генерации |

### Шаги проверки

Для проверки успешной сборки:

```
# 1. Проверьте существование dist/ и наличие файлов
ls -la dist/

# 2. Убедитесь, что главные точки входа существуют
ls -la dist/index.js dist/index.d.ts

# 3. Проверьте, что белый список CVA актуален
cat src/lib/core-classes.json | grep count

# 4. Убедитесь, что реестр текущий
cat src/registry.json | grep version
```

**Источники:** [package.json21-28](https://github.com/ui8kit/core/blob/2afe2195/package.json#L21-L28) [tsconfig.json1-26](https://github.com/ui8kit/core/blob/2afe2195/tsconfig.json#L1-L26)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.