Реестр компонентов

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

Реестр компонентов — это централизованная система метаданных, которая каталогизирует все компоненты в @ui8kit/core и обеспечивает несколько паттернов установки и использования. Реестр определен в src/registry.json1-281 и предоставляет структурированные метаданные, включая названия компонентов, типы, зависимости, пути к файлам и целевые директории. Эта страница документирует формат реестра, схему метаданных компонентов, процесс регистрации и то, как реестр поддерживает различные методы установки. Для получения информации о конвейере сборки, который генерирует артефакты реестра, см. Система сборки. Для получения подробной информации о распространении пакета см. Структура пакета. Источники: src/registry.json1-281 README.md251-276

Структура файла реестра

Реестр представляет собой JSON-файл, соответствующий схеме buildy-ui. Он содержит три свойства верхнего уровня:

Свойство	Тип	Описание
`$schema`	string	URL JSON-схемы для валидации
`items`	array	Массив объектов метаданных компонентов
`version`	string	Версия схемы реестра (в настоящее время “1.0.0”)
`lastUpdated`	string	Временная метка последнего обновления в формате ISO 8601
`registry`	string	Идентификатор реестра (“ui”)

Источники: src/registry.json2-281

Диаграмма схемы реестра

registry.json

$schema: buildy.tw/schema/registry.json

items[]
Массив метаданных компонентов

version: 1.0.0

lastUpdated: временная метка ISO 8601

registry: ui

Объект метаданных компонента

name: string

type: registry:ui | registry:layout

description: string

dependencies: string[]

devDependencies: string[]

files[]

path: путь источника

target: целевая директория

Источники: src/registry.json2-10 src/registry.json278-281

Схема метаданных компонента

Каждая запись компонента в массиве items содержит следующие поля:

Поле	Тип	Обязательное	Описание
`name`	string	Да	Название компонента (например, “Button”, “Card”)
`type`	string	Да	Категория компонента: “registry:ui” или “registry:layout”
`description`	string	Да	Описание компонента (может быть пустой строкой)
`dependencies`	string[]	Да	Зависимости времени выполнения (например, “react”, “lucide-react”)
`devDependencies`	string[]	Да	Зависимости разработки (обычно пустой массив)
`files`	object[]	Да	Массив объектов метаданных файлов
`files[].path`	string	Да	Путь к исходному файлу относительно корня репозитория
`files[].target`	string	Да	Целевая директория в проекте потребителя

Источники: src/registry.json4-17

Распределение типов компонентов

Реестр содержит 18 компонентов двух типов:

Тип	Количество	Компоненты
`registry:ui`	15	Title, Text, Stack, Sheet, Image, Icon, Group, Grid, Container, Card, Button, Box, Block, Badge, Accordion
`registry:layout`	3	SplitBlock, LayoutBlock, DashLayout

Источники: src/registry.json2-276

Пример записи компонента

Компонент Button демонстрирует минимальную запись реестра:

{
  "name": "Button",
  "type": "registry:ui",
  "description": "",
  "dependencies": ["react"],
  "devDependencies": [],
  "files": [
    {
      "path": "src/components/ui/Button/Button.tsx",
      "target": "components/ui"
    }
  ]
}

Источники: src/registry.json156-169

Классификация зависимостей

Реестр отслеживает две категории зависимостей для каждого компонента:

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

Компоненты объявляют зависимости времени выполнения, которые должны быть установлены в приложении потребителя:

Зависимость	Используется в	Назначение
`react`	Все компоненты	Основная библиотека React
`lucide-react`	Sheet, Accordion	Компоненты иконок (ChevronRight, X)
`react-resizable-panels`	DashLayout	Система макета с изменяемыми панелями

Примечание: class-variance-authority, clsx и tailwind-merge являются зависимостями уровня пакета, определенными в package.json48-53 и не отслеживаются для каждого компонента.

Зависимости разработки

Массив devDependencies присутствует во всех записях, но обычно пуст, поскольку зависимости разработки управляются на уровне пакета в package.json59-66 Источники: src/registry.json8-10 src/registry.json54-56 src/registry.json266-268 package.json48-53

Сопоставление путей к файлам

Каждая запись компонента сопоставляет исходные файлы с целевыми директориями в проекте потребителя:

Структура целевых директорий

Целевая директория	Назначение	Компоненты
`components/ui`	UI-компоненты	15 компонентов (Button, Card и т.д.)
`layouts`	Шаблоны макетов	3 компонента (DashLayout, LayoutBlock, SplitBlock)

Диаграмма сопоставления файлов

Проект потребителя

Метаданные реестра

Исходный репозиторий

src/components/ui/Button/Button.tsx

src/layouts/DashLayout.tsx

Запись Button
path: src/components/ui/Button/Button.tsx
target: components/ui

Запись DashLayout
path: src/layouts/DashLayout.tsx
target: layouts

components/ui/Button.tsx

layouts/DashLayout.tsx

Источники: src/registry.json14-16 src/registry.json240-243 src/registry.json272-274

Генерация реестра

Реестр генерируется и поддерживается с помощью инструмента CLI buildy-ui:

Команда Scan

Скрипт scan в package.json26 выполняет сканер buildy-ui:

bunx buildy-ui@latest scan

Эта команда:

Сканирует директории компонентов (src/components/ui/, src/layouts/)
Извлекает метаданные компонентов из исходных файлов
Определяет зависимости путем анализа импортов
Обновляет src/registry.json1-281 текущими метаданными
Устанавливает временную метку lastUpdated на текущее время ISO 8601

Источники: package.json26 src/registry.json279

Команда Build Registry

Скрипт build:r в package.json27 генерирует артефакты для распространения:

bunx buildy-ui@latest build

Это создает опубликованный пакет реестра в packages/registry/ для программного доступа. Источники: package.json27-28

Интеграция с методами установки

Реестр поддерживает четыре различных паттерна установки:

Сравнение методов установки

Метод	Команда	Использование реестра	Случай использования
Полная библиотека	`npm install @ui8kit/core`	Не используется (устанавливает весь пакет)	Комплексные проекты
По компонентам	`npx buildy-ui add button`	Читает метаданные для выборочной установки	Оптимизация бандла
Программный доступ	`import registry from 'registry.json'`	Прямой доступ к JSON	Инструменты/автоматизация
Git Submodule	`git submodule add`	Не используется (клонирует исходники)	Архитектуры монорепозитория

Источники: README.md255-276

Поток установки по компонентам

Отсутствует

Присутствует

npx buildy-ui add button

src/registry.json

Поиск 'button' в массиве items

Извлечение метаданных:
name: Button
type: registry:ui
files: src/components/ui/Button/Button.tsx
dependencies: react

Получение файла с GitHub:
ui8kit/core/src/components/ui/Button/Button.tsx

Проверка зависимостей:
Установлен ли react?

Установка отсутствующих зависимостей:
npm install react

Запись в целевую директорию:
components/ui/Button.tsx

Установка завершена

Источники: README.md261-265 src/registry.json156-169

Программный доступ к реестру

Приложения могут импортировать JSON реестра для автоматизации и инструментов:

Структура данных реестра

interface RegistryFile {
  $schema: string;
  items: ComponentItem[];
  version: string;
  lastUpdated: string;
  registry: string;
}

interface ComponentItem {
  name: string;
  type: "registry:ui" | "registry:layout";
  description: string;
  dependencies: string[];
  devDependencies: string[];
  files: FileItem[];
}

interface FileItem {
  path: string;
  target: string;
}

Пример использования

import registry from '@ui8kit/core/registry.json';

// Список всех UI-компонентов
const uiComponents = registry.items
  .filter(item => item.type === 'registry:ui')
  .map(item => item.name);

// Поиск компонентов, требующих lucide-react
const iconComponents = registry.items
  .filter(item => item.dependencies.includes('lucide-react'))
  .map(item => item.name);
// Результат: ["Sheet", "Accordion"]

// Получение целевых директорий установки
const targets = [...new Set(
  registry.items.flatMap(item => 
    item.files.map(file => file.target)
  )
)];
// Результат: ["components/ui", "layouts"]

Источники: README.md268-276 src/registry.json1-281

Покрытие компонентов

Реестр обеспечивает полное покрытие иерархии компонентов библиотеки:

Инвентаризация компонентов по слоям

Слой 3: Макеты

Слой 2: UI-компоненты

Слой 1: Базовые примитивы

Записи реестра: всего 18

registry:ui
15 компонентов

registry:layout
3 компонента

Box
src/components/ui/Box/Box.tsx

Block
src/components/ui/Block/Block.tsx

Grid
src/components/ui/Grid/Grid.tsx

Stack
src/components/ui/Stack/Stack.tsx

Button
src/components/ui/Button/Button.tsx

Card
src/components/ui/Card/Card.tsx

Text
src/components/ui/Text/Text.tsx

Title
src/components/ui/Title/Title.tsx

Container
src/components/ui/Container/Container.tsx

Icon
src/components/ui/Icon/Icon.tsx

Image
src/components/ui/Image/Image.tsx

Badge
src/components/ui/Badge/Badge.tsx

Group
src/components/ui/Group/Group.tsx

Sheet
src/components/ui/Sheet/Sheet.tsx

Accordion
src/components/ui/Accordion/Accordion.tsx

DashLayout
src/layouts/DashLayout.tsx

LayoutBlock
src/layouts/LayoutBlock.tsx

SplitBlock
src/layouts/SplitBlock.tsx

Источники: src/registry.json1-276

Обслуживание реестра

Управление версиями

Реестр использует семантическое версионирование независимо от версии пакета:

Версия реестра: src/registry.json278 - В настоящее время “1.0.0”
Версия пакета: package.json3 - В настоящее время “0.1.8”

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

Временная метка последнего обновления

Поле lastUpdated в src/registry.json279 записывает время последнего изменения в виде строки ISO 8601:

"lastUpdated": "2025-10-30T13:21:21.408Z"

Эта временная метка обновляется автоматически при выполнении npm run scan. Источники: src/registry.json278-281 package.json3 package.json26

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

Реестр распространяется через два канала:

Распространение через NPM пакет

JSON реестра включен в NPM пакет через поле files в package.json39-42:

"files": [
  "dist/**/*",
  "README.md",
  "LICENSE"
]

Примечание: registry.json не указан явно здесь, но включен в NPM tarball для программного доступа.

Отдельный пакет реестра

Скрипт publish в package.json28 публикует отдельный пакет реестра:

cd packages/registry && npm version patch && npm publish

Это создает отдельный NPM пакет, содержащий только метаданные реестра для облегченного доступа инструментами CLI. Источники: package.json28 package.json39-42

Интеграция с конвейером сборки

Реестр взаимодействует с другими системами времени сборки:

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

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

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

Исходные файлы

сканирует

генерирует

компилирует

генерирует

извлекает

генерирует

включен в

опубликован как

включен в

ссылается в

src/components/ui/**/.tsx
src/layouts/.tsx

buildy-ui scan

Компилятор TypeScript

Экстрактор CVA

src/registry.json

dist/

src/lib/core-classes.json

NPM пакет
@ui8kit/core

Пакет реестра

Источники: package.json22-28 src/registry.json1-281

Резюме

Реестр компонентов служит единым источником истины для метаданных компонентов в @ui8kit/core. Он обеспечивает:

Установку по компонентам через npx buildy-ui add [component]
Программный доступ для инструментов и автоматизации
Отслеживание зависимостей для выборочных установок
Сопоставление путей к файлам от источника к целевым директориям
Классификацию компонентов по типу (UI vs Layout)

Реестр автоматически поддерживается с помощью команды buildy-ui scan и распространяется через NPM вместе со скомпилированным пакетом. Источники: src/registry.json1-281 README.md251-276 package.json26-28

Getting started

Architecture

Components

Development Guide

Реестр компонентов

Реестр компонентов

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

Структура файла реестра

Диаграмма схемы реестра

Схема метаданных компонента

Распределение типов компонентов

Пример записи компонента

Классификация зависимостей

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

Зависимости разработки

Сопоставление путей к файлам

Структура целевых директорий

Диаграмма сопоставления файлов

Генерация реестра

Команда Scan

Команда Build Registry

Интеграция с методами установки

Сравнение методов установки

Поток установки по компонентам

Программный доступ к реестру

Структура данных реестра

Пример использования

Покрытие компонентов

Инвентаризация компонентов по слоям

Обслуживание реестра

Управление версиями

Временная метка последнего обновления

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

Распространение через NPM пакет

Отдельный пакет реестра

Интеграция с конвейером сборки

Резюме

​Реестр компонентов

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

​Структура файла реестра

​Диаграмма схемы реестра

​Схема метаданных компонента

​Распределение типов компонентов

​Пример записи компонента

​Классификация зависимостей

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

​Зависимости разработки

​Сопоставление путей к файлам

​Структура целевых директорий

​Диаграмма сопоставления файлов

​Генерация реестра

​Команда Scan

​Команда Build Registry

​Интеграция с методами установки

​Сравнение методов установки

​Поток установки по компонентам

​Программный доступ к реестру

​Структура данных реестра

​Пример использования

​Покрытие компонентов

​Инвентаризация компонентов по слоям

​Обслуживание реестра

​Управление версиями

​Временная метка последнего обновления

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

​Распространение через NPM пакет

​Отдельный пакет реестра

​Интеграция с конвейером сборки

​Резюме

Реестр компонентов

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

Структура файла реестра

Диаграмма схемы реестра

Схема метаданных компонента

Распределение типов компонентов

Пример записи компонента

Классификация зависимостей

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

Зависимости разработки

Сопоставление путей к файлам

Структура целевых директорий

Диаграмма сопоставления файлов

Генерация реестра

Команда Scan

Команда Build Registry

Интеграция с методами установки

Сравнение методов установки

Поток установки по компонентам

Программный доступ к реестру

Структура данных реестра

Пример использования

Покрытие компонентов

Инвентаризация компонентов по слоям

Обслуживание реестра

Управление версиями

Временная метка последнего обновления

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

Распространение через NPM пакет

Отдельный пакет реестра

Интеграция с конвейером сборки

Резюме