Skip to main content

​
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:
PropertyTypeDescription
$schemastringJSON schema URL for validation
itemsarrayArray of component metadata objects
versionstringRegistry schema version (currently “1.0.0”)
lastUpdatedstringISO 8601 timestamp of last update
registrystringRegistry 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:
FieldTypeRequiredDescription
namestringYesComponent name (e.g., “Button”, “Card”)
typestringYesComponent category: “registry:ui” or “registry:layout”
descriptionstringYesComponent description (may be empty string)
dependenciesstring[]YesRuntime dependencies (e.g., “react”, “lucide-react”)
devDependenciesstring[]YesDevelopment dependencies (typically empty)
filesobject[]YesArray of file metadata objects
files[].pathstringYesSource file path relative to repo root
files[].targetstringYesTarget directory in consumer project
Sources: src/registry.json4-17

​
Component Types Distribution

The registry contains 18 components across two types:
TypeCountComponents
registry:ui15Title, Text, Stack, Sheet, Image, Icon, Group, Grid, Container, Card, Button, Box, Block, Badge, Accordion
registry:layout3SplitBlock, 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:
DependencyUsed ByPurpose
reactAll componentsCore React library
lucide-reactSheet, AccordionIcon components (ChevronRight, X)
react-resizable-panelsDashLayoutResizable 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

TargetPurposeComponents
components/uiUI components15 components (Button, Card, etc.)
layoutsLayout templates3 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:
  1. Scans component directories (src/components/ui/, src/layouts/)
  2. Extracts component metadata from source files
  3. Determines dependencies by analyzing imports
  4. Updates src/registry.json1-281 with current metadata
  5. 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

MethodCommandRegistry UsageUse Case
Full Librarynpm install @ui8kit/coreNot used (installs entire package)Comprehensive projects
Per-Componentnpx buildy-ui add buttonReads metadata for selective installBundle optimization
Programmaticimport registry from 'registry.json'Direct JSON accessTooling/automation
Git Submodulegit submodule addNot 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: 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:
  1. Per-component installation via npx buildy-ui add [component]
  2. Programmatic access for tooling and automation
  3. Dependency tracking for selective installations
  4. File path mapping from source to target directories
  5. 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