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 и обеспечивает несколько паттернов установки и использования. Реестр определен в 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”) |
Диаграмма схемы реестра
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: целевая директория
Схема метаданных компонента
Каждая запись компонента в массиве 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 | Да | Целевая директория в проекте потребителя |
Распределение типов компонентов
Реестр содержит 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 |
Пример записи компонента
Компонент Button демонстрирует минимальную запись реестра:
{
"name": "Button",
"type": "registry:ui",
"description": "",
"dependencies": ["react"],
"devDependencies": [],
"files": [
{
"path": "src/components/ui/Button/Button.tsx",
"target": "components/ui"
}
]
}
Классификация зависимостей
Реестр отслеживает две категории зависимостей для каждого компонента:
Зависимости времени выполнения
Компоненты объявляют зависимости времени выполнения, которые должны быть установлены в приложении потребителя:
| Зависимость | Используется в | Назначение |
|---|
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
Генерация реестра
Реестр генерируется и поддерживается с помощью инструмента 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 | Не используется (клонирует исходники) | Архитектуры монорепозитория |
Поток установки по компонентам
Отсутствует
Присутствует
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
Установка завершена
Программный доступ к реестру
Приложения могут импортировать 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"]
Покрытие компонентов
Реестр обеспечивает полное покрытие иерархии компонентов библиотеки:
Инвентаризация компонентов по слоям
Слой 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
Обслуживание реестра
Управление версиями
Реестр использует семантическое версионирование независимо от версии пакета:
Версия реестра изменяется при изменении схемы метаданных, а не при добавлении или изменении компонентов.
Временная метка последнего обновления
Поле 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"
]
Отдельный пакет реестра
Скрипт publish в package.json28 публикует отдельный пакет реестра:
cd packages/registry && npm version patch && npm publish
Интеграция с конвейером сборки
Реестр взаимодействует с другими системами времени сборки:
Распространение
Артефакты сборки
Инструменты времени сборки
Исходные файлы
сканирует
генерирует
компилирует
генерирует
извлекает
генерирует
включен в
опубликован как
включен в
ссылается в
src/components/ui/**/.tsx
src/layouts/.tsx
buildy-ui scan
Компилятор TypeScript
Экстрактор CVA
src/registry.json
dist/
src/lib/core-classes.json
NPM пакет
@ui8kit/core
Пакет реестра
Резюме
Реестр компонентов служит единым источником истины для метаданных компонентов в @ui8kit/core. Он обеспечивает:
- Установку по компонентам через
npx buildy-ui add [component]
- Программный доступ для инструментов и автоматизации
- Отслеживание зависимостей для выборочных установок
- Сопоставление путей к файлам от источника к целевым директориям
- Классификацию компонентов по типу (UI vs Layout)
Реестр автоматически поддерживается с помощью команды buildy-ui scan и распространяется через NPM вместе со скомпилированным пакетом.
Источники: src/registry.json1-281 README.md251-276 package.json26-28
