Overview

Relevant source files

• CONTRIBUTING.md
• README.md
• apps/v4/lib/source.ts
• apps/v4/package.json
• apps/v4/registry.json
• apps/v4/registry/README.md
• apps/v4/scripts/build-registry.mts
• package.json
• packages/shadcn/CHANGELOG.md
• packages/shadcn/package.json
• pnpm-lock.yaml

The shadcn/ui repository is a component library system designed to distribute components as source code instead of traditional precompiled npm packages. Developers use a CLI tool to add, customize, and extend these components directly in their projects, giving them full ownership over their UI README.md1-3 The repository employs a registry-first architecture, where component metadata and source files are served through a public API. Both the documentation website and the CLI installer consume this API to deliver components to users apps/v4/package.json17-18

This wiki documents the technical architecture, build processes, and organization of the codebase maintained at https

---

Scope of This Page

This page provides a high-level overview of the repository structure, core systems, and how they interact. Detailed information on specific subsystems is available on child pages:

• For the overall system architecture including workspace monorepo, CLI, registry, and website, see Architecture Overview.
• For fundamental concepts such as the component source model, registries, styles, and presets, see Key Concepts.

Sources: README.md1-18 CONTRIBUTING.md9-42 pnpm-lock.yaml11-121

---

Repository Architecture

The shadcn/ui repository is a pnpm-based monorepo managed with Turborepo CONTRIBUTING.md11-15 It is organized into three main systems:

1. Registry & Website (apps/v4/):
   A Next.js application that serves the documentation and the public registry API. It contains authored component sources and the build pipeline for generating registry JSON files apps/v4/package.json7-8

   • Authored components: registry/bases/ apps/v4/registry/README.md10-13
   • Build scripts: scripts/build-registry.mts apps/v4/scripts/build-registry.mts28-66

2. CLI Tool (packages/shadcn/):
   The shadcn CLI tool that installs components by fetching from the registry and applying code transformations packages/shadcn/package.json2-4

   • CLI Entry: dist/index.js (compiled from src/index.ts) packages/shadcn/package.json64
   • MCP Server: dist/mcp/index.js for AI integration packages/shadcn/package.json43-46

3. Supporting Infrastructure:
   Includes templates/ for scaffolding and GitHub Actions for releases using Changesets CONTRIBUTING.md15-17

---

Architecture Interaction Diagram

The following diagram bridges the system architecture with specific code entities.

Sources: CONTRIBUTING.md17-42 apps/v4/package.json1-23 packages/shadcn/package.json1-63 package.json11-14

---

Core Systems and Data Flow

The repository uses a build-time registry generation approach. Components are authored in a "base" format and then transformed into various styles (e.g., nova, sera) and distributed as JSON metadata apps/v4/registry/README.md3-6

Component Distribution Flow

This diagram traces a component from authored source to a user's local project.

Sources: apps/v4/package.json17-18 apps/v4/registry/README.md22-35 packages/shadcn/package.json68-82

---

Technology Stack

• Framework: Next.js 16 (Canary) and React 19 apps/v4/package.json76-81
• Styling: Tailwind CSS v4 apps/v4/package.json119
• CLI Core: TypeScript, ts-morph for AST manipulation, commander for CLI parsing, and zod for validation packages/shadcn/package.json88-118
• Headless Primitives: Uses @radix-ui and the new @base-ui/react apps/v4/package.json29-80
• AI Integration: Model Context Protocol (MCP) server integration packages/shadcn/package.json43-46

Sources: apps/v4/package.json25-103 packages/shadcn/package.json87-120 pnpm-lock.yaml7-10

---

Key Architectural Patterns

Registry-First Architecture

Components are defined as RegistryItem objects in shadcn/schema. This metadata includes dependencies, files, and CSS variables, allowing the CLI to resolve the full tree of requirements for a component apps/v4/scripts/build-registry.mts11-17

Multi-Registry Ecosystem

The system supports multiple registries (official, community, and private). The CLI can resolve components across different namespaces and handles authentication for private registries packages/shadcn/CHANGELOG.md19-61

---

Developer Entry Points

Running Locally

1. Install: pnpm install CONTRIBUTING.md70-71
2. Build Registry: pnpm registry:build in apps/v4 to generate local styles and public artifacts apps/v4/package.json18
3. Run Web: pnpm --filter=v4 dev CONTRIBUTING.md82-83
4. Test CLI: pnpm shadcn runs the CLI in development mode package.json23

Release Process

Release management is handled via Changesets package.json37

• pnpm release: Versioning packages/shadcn/package.json78
• pnpm pub:release: Publishing to npm packages/shadcn/package.json82

---

Summary Table: System Components

System	Path	Key Code Entity
CLI	packages/shadcn	src/index.ts (Entry), src/mcp (AI)
Registry Source	apps/v4/registry	bases/, styles/, new-york-v4/
Registry Build	apps/v4/scripts	build-registry.mts
Web Application	apps/v4/app	Next.js App Router
Headless Primitives	packages/react	@shadcn/react
AI Helpers	packages/helpers	@shadcn/helpers

Sources: CONTRIBUTING.md17-42 apps/v4/package.json1-23 packages/shadcn/package.json1-63