This document provides a detailed technical explanation of the registry architecture in the shadcn/ui codebase. It covers how components are organized into bases and styles, the structure and types of registry items, the build pipeline that generates registry manifests and component variants, and how the CLI handles these registries for component installation.
The registry system in shadcn/ui acts as a distributed source delivery network for UI components. Rather than shipping compiled binaries or bundled libraries via NPM, it delivers raw TypeScript/TSX source files along with JSON manifests describing metadata like dependencies, files, and styles. This design allows flexible combination of base component implementations and visual styles, enabling multiple design systems and themes to co-exist.
| Layer | Responsibility | Key Entities / Files |
|---|---|---|
| Source Code | Raw component implementations and style tokens | registry/bases, registry/styles directories |
| Registry Manifests | JSON metadata defining components and styles | registry.json, __index__.tsx, style JSON files |
| Build Pipeline | Code transformation and registry compilation | scripts/build-registry.mts |
| Distribution | Output of public JSON registries and generated files | public/r/styles/[style]/registry.json, styles/ |
Sources: apps/v4/scripts/build-registry.mts26-58 apps/v4/registry.json1-25
A fundamental design principle in the registry is the separation of Bases and Styles forming a composable matrix.
A Base provides the underlying functional logic and component implementation. Each base corresponds to a set of primitives or foundational UI libraries.
@radix-ui/react-*) as foundations. Considered the default base in many scenarios.@base-ui/react.@react-aria primitives.Each base defines a component set within registry/bases/{base-name} with source code files. For example, the Radix base components are in registry/bases/radix/ui/*.tsx while Base UI's components reside in registry/bases/base/ui/*.tsx.
Sources: apps/v4/scripts/build-registry.mts31-32 apps/v4/registry/bases/__index__.tsx7-30 apps/v4/registry/config.ts145-158 packages/shadcn/src/preset/presets.ts145-158
A Style defines the visual design system, including theme colors, spacing, and CSS frameworks, predominantly using TailwindCSS utilities.
@apply directives or custom variables: registry/styles/style-*.css.nova, vega, maia, lyra, mira, luma, sera, rhea, and the legacy new-york-v4.Sources: apps/v4/scripts/build-registry.mts33 apps/v4/registry/config.ts12-20 apps/v4/public/schema.json7-34
The build system generates all combinations of bases and styles into individual registries, enabling a flexible design system where:
{base-name}-{style-name}.radix-nova combines the Radix base with the Nova style, while base-mira combines Base UI base with the Mira style.Figure 1: Registry Base and Style Combinatorial Matrix
Sources: apps/v4/scripts/build-registry.mts68-75 apps/v4/registry/config.ts191-234 apps/v4/public/schema.json10-33
The registry manifest (registry.json files) describes components and related items with type annotations that determine their handling.
| Type | Description | Example |
|---|---|---|
registry:ui | Atomic UI components implemented as React TSX files | accordion.tsx, button.tsx |
registry:block | Composite components or patterns consisting of multiple components | sidebar-01 composition block |
registry:style | Global style definitions, TailwindCSS config layers | index, style items defining CSS applies |
registry:theme | Theme-specific customizations or color token definitions | theme-blue |
registry:example | Example source code to demonstrate usage | accordion-demo.tsx |
registry:base | Base configuration for a registry project | registry-base containing components.json defaults |
Each item includes metadata with dependencies, registryDependencies (internal registry items it depends on), files, and optional style or theme CSS variables.
Files within an item specify:
path: the relative file path for the source or style file.type: the file type (usually matching the item's type).target: optional install location override.Sources: apps/v4/registry.json5-13 apps/v4/registry.json24-33 apps/v4/registry/config.ts30-31 packages/shadcn/src/preset/presets.ts261-262
The primary manifest anchor file registry.json contains a top-level object:
"name": Registry name "shadcn/ui"."homepage": URL for project homepage."items": Array of registry items (components, styles, themes).Each item looks like this minimal example for the accordion UI component:
Sources: apps/v4/registry.json1-33 apps/v4/registry/__index__.tsx7-23
The build pipeline is a centralized script scripts/build-registry.mts that compiles the registry from authored sources and styles into distributable artifacts.
registry/bases/{base-name} apps/v4/scripts/build-registry.mts49registry/styles to produce style-specific registries apps/v4/scripts/build-registry.mts50transformDirection), style (transformStyle), and icon sets (transformIcons) apps/v4/scripts/build-registry.mts12-17registry/__index__.tsx, examples/__index__.tsx) apps/v4/scripts/build-registry.mts51-53public/r/styles/<style>/registry.json for CLI consumption apps/v4/scripts/build-registry.mts54styles/<style>/ui/* apps/v4/scripts/build-registry.mts55Figure 2: Registry Build Pipeline Data Flow
Sources: apps/v4/scripts/build-registry.mts48-59 apps/v4/scripts/build-registry.mts68-75
For runtime usage, generated files provide indexes and metadata:
registry/__index__.tsx: Metadata index mapping style names to components and their files apps/v4/registry/__index__.tsx6-23examples/__index__.tsx: Index of authored demos and their file paths apps/v4/examples/__index__.tsx6-20registry/bases/__index__.tsx: Source-of-truth index for the raw base implementations apps/v4/registry/bases/__index__.tsx6-30These indexes enable the shadcn UI website and CLI tooling to quickly query component metadata (dependencies, files, types) and dynamically load component code for previews.
Sources: apps/v4/registry/__index__.tsx1-40 apps/v4/examples/__index__.tsx1-40 apps/v4/registry/bases/__index__.tsx1-40
The CLI interacts with the registry by fetching style-specific manifests to resolve the full dependency tree.
Figure 3: End-to-End Component Distribution and Installation Flow
Sources: apps/v4/scripts/build-registry.mts54-55 packages/shadcn/src/preset/presets.ts225-250 apps/v4/registry.json24-33
The shadcn/ui registry architecture leverages a matrix of:
The build pipeline (build-registry.mts) orchestrates the transformation of these raw sources into a distributed JSON-based registry system. This allows the CLI to perform just-in-time source delivery, ensuring that users receive the exact code variants matching their project configuration.
Figure 4: Core Code Entities and Their Relations
Sources: apps/v4/scripts/build-registry.mts20-25 apps/v4/registry/config.ts1-25 apps/v4/registry/__index__.tsx1-40
apps/v4/scripts/build-registry.mts apps/v4/scripts/build-registry.mts1-66apps/v4/registry/config.ts apps/v4/registry/config.ts1-30apps/v4/registry/__index__.tsx apps/v4/registry/__index__.tsx1-150apps/v4/public/schema.json apps/v4/public/schema.json1-141Sources: apps/v4/scripts/build-registry.mts1-66 apps/v4/registry/config.ts1-30 apps/v4/registry/__index__.tsx1-150 apps/v4/public/schema.json1-141
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.