Component Registry

Relevant source files

Purpose and Scope

The Component Registry is a centralized metadata system that catalogs all components in @ui8kit/core and enables multiple installation and consumption patterns. The registry is defined in src/registry.json1-281 and provides structured metadata including component names, types, dependencies, file paths, and target directories. This page documents the registry format, component metadata schema, registration process, and how the registry powers different installation methods. For information about the build pipeline that generates registry artifacts, see Build System. For details on package distribution, see Package Structure. Sources: src/registry.json1-281 README.md251-276

Registry File Structure

The registry is a JSON file conforming to the buildy-ui schema. It contains three top-level properties:

Property	Type	Description
`$schema`	string	JSON schema URL for validation
`items`	array	Array of component metadata objects
`version`	string	Registry schema version (currently “1.0.0”)
`lastUpdated`	string	ISO 8601 timestamp of last update
`registry`	string	Registry identifier (“ui”)

Sources: src/registry.json2-281

Registry Schema Diagram

registry.json

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

items[]
Component metadata array

version: 1.0.0

lastUpdated: ISO 8601 timestamp

registry: ui

Component Metadata Object

name: string

type: registry:ui | registry:layout

description: string

dependencies: string[]

devDependencies: string[]

files[]

path: src path

target: destination directory

Sources: src/registry.json2-10 src/registry.json278-281

Component Metadata Schema

Each component entry in the items array contains the following fields:

Field	Type	Required	Description
`name`	string	Yes	Component name (e.g., “Button”, “Card”)
`type`	string	Yes	Component category: “registry:ui” or “registry:layout”
`description`	string	Yes	Component description (may be empty string)
`dependencies`	string[]	Yes	Runtime dependencies (e.g., “react”, “lucide-react”)
`devDependencies`	string[]	Yes	Development dependencies (typically empty)
`files`	object[]	Yes	Array of file metadata objects
`files[].path`	string	Yes	Source file path relative to repo root
`files[].target`	string	Yes	Target directory in consumer project

Sources: src/registry.json4-17

Component Types Distribution

The registry contains 18 components across two types:

Type	Count	Components
`registry:ui`	15	Title, Text, Stack, Sheet, Image, Icon, Group, Grid, Container, Card, Button, Box, Block, Badge, Accordion
`registry:layout`	3	SplitBlock, LayoutBlock, DashLayout

Sources: src/registry.json2-276

Example Component Entry

The Button component demonstrates a minimal registry entry:

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

Sources: src/registry.json156-169

Dependency Classification

The registry tracks two categories of dependencies for each component:

Runtime Dependencies

Components declare runtime dependencies that must be installed in the consumer application:

Dependency	Used By	Purpose
`react`	All components	Core React library
`lucide-react`	Sheet, Accordion	Icon components (ChevronRight, X)
`react-resizable-panels`	DashLayout	Resizable panel layout system

Note: class-variance-authority, clsx, and tailwind-merge are package-level dependencies defined in package.json48-53 and not tracked per-component.

Development Dependencies

The devDependencies array is present in all entries but typically empty, as development dependencies are managed at the package level in package.json59-66 Sources: src/registry.json8-10 src/registry.json54-56 src/registry.json266-268 package.json48-53

File Path Mapping

Each component entry maps source files to target directories in the consumer project:

Target Directory Structure

Target	Purpose	Components
`components/ui`	UI components	15 components (Button, Card, etc.)
`layouts`	Layout templates	3 components (DashLayout, LayoutBlock, SplitBlock)

File Mapping Diagram

Consumer Project

Registry Metadata

Source Repository

src/components/ui/Button/Button.tsx

src/layouts/DashLayout.tsx

Button entry
path: src/components/ui/Button/Button.tsx
target: components/ui

DashLayout entry
path: src/layouts/DashLayout.tsx
target: layouts

components/ui/Button.tsx

layouts/DashLayout.tsx

Sources: src/registry.json14-16 src/registry.json240-243 src/registry.json272-274

Registry Generation

The registry is generated and maintained through the buildy-ui CLI tool:

Scan Command

The scan script in package.json26 executes the buildy-ui scanner:

bunx buildy-ui@latest scan

This command:

Scans component directories (src/components/ui/, src/layouts/)
Extracts component metadata from source files
Determines dependencies by analyzing imports
Updates src/registry.json1-281 with current metadata
Sets lastUpdated timestamp to current ISO 8601 time

Sources: package.json26 src/registry.json279

Build Registry Command

The build:r script in package.json27 generates distribution artifacts:

bunx buildy-ui@latest build

This creates the published registry package at packages/registry/ for programmatic access. Sources: package.json27-28

Integration with Installation Methods

The registry powers four distinct installation patterns:

Installation Methods Comparison

Method	Command	Registry Usage	Use Case
Full Library	`npm install @ui8kit/core`	Not used (installs entire package)	Comprehensive projects
Per-Component	`npx buildy-ui add button`	Reads metadata for selective install	Bundle optimization
Programmatic	`import registry from 'registry.json'`	Direct JSON access	Tooling/automation
Git Submodule	`git submodule add`	Not used (clones source)	Monorepo architectures

Sources: README.md255-276

Per-Component Installation Flow

Missing

Present

npx buildy-ui add button

src/registry.json

Look up 'button' in items array

Extract metadata:
name: Button
type: registry:ui
files: src/components/ui/Button/Button.tsx
dependencies: react

Fetch file from GitHub:
ui8kit/core/src/components/ui/Button/Button.tsx

Check dependencies:
Is react installed?

Install missing dependencies:
npm install react

Write to target:
components/ui/Button.tsx

Installation complete

Sources: README.md261-265 src/registry.json156-169

Programmatic Registry Access

Applications can import the registry JSON for automation and tooling:

Registry Data Structure

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;
}

Example Usage

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

// List all UI components
const uiComponents = registry.items
  .filter(item => item.type === 'registry:ui')
  .map(item => item.name);

// Find components requiring lucide-react
const iconComponents = registry.items
  .filter(item => item.dependencies.includes('lucide-react'))
  .map(item => item.name);
// Result: ["Sheet", "Accordion"]

// Get installation targets
const targets = [...new Set(
  registry.items.flatMap(item => 
    item.files.map(file => file.target)
  )
)];
// Result: ["components/ui", "layouts"]

Sources: README.md268-276 src/registry.json1-281

Component Coverage

The registry provides complete coverage of the library’s component hierarchy:

Component Inventory by Layer

Layer 3: Layouts

Layer 2: UI Components

Layer 1: Core Primitives

Registry Items: 18 Total

registry:ui
15 components

registry:layout
3 components

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

Sources: src/registry.json1-276

Registry Maintenance

Version Management

The registry uses semantic versioning independently from the package version:

Registry Version: src/registry.json278 - Currently “1.0.0”
Package Version: package.json3 - Currently “0.1.8”

The registry version changes when the metadata schema changes, not when components are added or modified.

Last Updated Timestamp

The lastUpdated field in src/registry.json279 records the last modification time as an ISO 8601 string:

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

This timestamp updates automatically when running npm run scan. Sources: src/registry.json278-281 package.json3 package.json26

Registry Distribution

The registry is distributed through two channels:

NPM Package Distribution

The registry JSON is included in the NPM package through the files field in package.json39-42:

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

Note: The registry.json is not explicitly listed here but is included in the NPM tarball for programmatic access.

Standalone Registry Package

The publish script in package.json28 publishes a standalone registry package:

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

This creates a dedicated NPM package containing only the registry metadata for lightweight access by CLI tools. Sources: package.json28 package.json39-42

Integration with Build Pipeline

The registry interacts with other build-time systems:

Distribution

Build Artifacts

Build-Time Tools

Source Files

scans

generates

compiles

generates

extracts

generates

included in

published as

included in

referenced by

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

buildy-ui scan

TypeScript Compiler

CVA Extractor

src/registry.json

dist/

src/lib/core-classes.json

NPM Package
@ui8kit/core

Registry Package

Sources: package.json22-28 src/registry.json1-281

Summary

The Component Registry serves as the single source of truth for component metadata in @ui8kit/core. It enables:

Per-component installation via npx buildy-ui add [component]
Programmatic access for tooling and automation
Dependency tracking for selective installations
File path mapping from source to target directories
Component classification by type (UI vs Layout)

The registry is automatically maintained through the buildy-ui scan command and distributed via NPM alongside the compiled package. Sources: src/registry.json1-281 README.md251-276 package.json26-28

Getting started

Architecture

Components

Development Guide

Component Registry

Component Registry

Purpose and Scope

Registry File Structure

Registry Schema Diagram

Component Metadata Schema

Component Types Distribution

Example Component Entry

Dependency Classification

Runtime Dependencies

Development Dependencies

File Path Mapping

Target Directory Structure

File Mapping Diagram

Registry Generation

Scan Command

Build Registry Command

Integration with Installation Methods

Installation Methods Comparison

Per-Component Installation Flow

Programmatic Registry Access

Registry Data Structure

Example Usage

Component Coverage

Component Inventory by Layer

Registry Maintenance

Version Management

Last Updated Timestamp

Registry Distribution

NPM Package Distribution

Standalone Registry Package

Integration with Build Pipeline

Summary

​Component Registry

​Purpose and Scope

​Registry File Structure

​Registry Schema Diagram

​Component Metadata Schema

​Component Types Distribution

​Example Component Entry

​Dependency Classification

​Runtime Dependencies

​Development Dependencies

​File Path Mapping

​Target Directory Structure

​File Mapping Diagram

​Registry Generation

​Scan Command

​Build Registry Command

​Integration with Installation Methods

​Installation Methods Comparison

​Per-Component Installation Flow

​Programmatic Registry Access

​Registry Data Structure

​Example Usage

​Component Coverage

​Component Inventory by Layer

​Registry Maintenance

​Version Management

​Last Updated Timestamp

​Registry Distribution

​NPM Package Distribution

​Standalone Registry Package

​Integration with Build Pipeline

​Summary

Component Registry

Purpose and Scope

Registry File Structure

Registry Schema Diagram

Component Metadata Schema

Component Types Distribution

Example Component Entry

Dependency Classification

Runtime Dependencies

Development Dependencies

File Path Mapping

Target Directory Structure

File Mapping Diagram

Registry Generation

Scan Command

Build Registry Command

Integration with Installation Methods

Installation Methods Comparison

Per-Component Installation Flow

Programmatic Registry Access

Registry Data Structure

Example Usage

Component Coverage

Component Inventory by Layer

Registry Maintenance

Version Management

Last Updated Timestamp

Registry Distribution

NPM Package Distribution

Standalone Registry Package

Integration with Build Pipeline

Summary