# shadcn-ui/ui architecture

> Architecture diagram of the GitHub repository shadcn-ui/ui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shadcn-ui/ui
- Repository: https://github.com/shadcn-ui/ui

## Overview

#### Purpose and Workspace Shape
shadcn/ui is an open-source, copy-into-your-project component ecosystem: a CLI installs, customizes, migrates, and publishes registry content; a documentation site exposes components, blocks, themes, and generated artifacts. The pnpm/Turbo monorepo separates reusable packages, the site/registry source, templates, and integration tests.
- `package.json`
- `pnpm-workspace.yaml`
- `turbo.json`

#### Primary Entry Points
The CLI package is the consumer-facing executable and command dispatcher. Its commands cover initialization, adding/applying registry items, presets, migrations, registry operations, and MCP. The Next.js site is the public browsing, documentation, preview, and registry-serving application.
- `packages/shadcn/src/index.ts`
- `packages/shadcn/src/commands/add.ts`
- `apps/v4/app/layout.tsx`

#### CLI Project-Mutation Pipeline
CLI commands first inspect a target project’s framework, package manager, workspace layout, aliases, and `components.json`; then resolve requested registry items; transform source/CSS/imports for the target; update files, dependencies, environment variables, fonts, and Tailwind-related configuration. This is the critical boundary between declarative registry content and arbitrary user repositories, with dry-run and safety support.
- `packages/shadcn/src/registry/resolver.ts`
- `packages/shadcn/src/utils/add-components.ts`
- `packages/shadcn/src/utils/transformers/transform-import.ts`

#### Registry System and Distribution Artifacts
Registry definitions model components, examples, blocks, hooks, styles, icons, and themes. Source registries are organized by implementation base (`aria`, `base`, `radix`) and style variants; build scripts emit static JSON under the site’s public `/r` hierarchy, which the CLI can consume. Registry validation, fetching, GitHub access, proxying, namespaces, and schema handling are centralized in the CLI registry layer.
- `apps/v4/registry.json`
- `apps/v4/registry/bases/base/registry.ts`
- `apps/v4/public/r/styles/default/index.json`

#### Documentation, Catalog, and Preview Site
The Next.js App Router site renders MDX documentation, component/block catalogs, examples, charts, colors, and generated previews. Shared server-side libraries derive page trees, docs content, registry metadata, source, themes, and blocks. Separate view routes render isolated component/example/type previews, supporting the interactive catalog and embed/iframe-style presentation boundary.
- `apps/v4/app/(app)/docs/[[...slug]]/page.tsx`
- `apps/v4/content/docs/components/meta.json`
- `apps/v4/app/(view)/view/[style]/[name]/page.tsx`

#### Interactive Design Tools and APIs
`/create` and `/typeset` are stateful client experiences for configuring visual systems, presets, fonts, themes, and previews, including history, locking, randomization, and iframe synchronization. Site route handlers expose search, registry discovery, LLM-oriented content, RSS, Open Graph images, and CSS/registry endpoints. External integrations are indicated by v0 initiation routes and GitHub-backed registry support; no database service is evident from the supplied tree.
- `apps/v4/app/(app)/(create)/create/page.tsx`
- `apps/v4/app/(app)/(create)/init/v0/route.ts`
- `apps/v4/app/api/search/route.ts`

#### Reusable Runtime Packages and Templates
`@shadcn/react` provides higher-level React primitives such as message scrolling and questionnaires. `@shadcn/helpers` supplies framework-adapter utilities for AI SDK and TanStack AI message/chat representations. The CLI scaffolds or packages framework-specific starter templates for Next.js, Vite, Astro, React Router, and TanStack Start, including monorepo variants.
- `packages/react/src/message-scroller/index.ts`
- `packages/helpers/src/core/index.ts`
- `packages/shadcn/src/templates/create-template.ts`

#### Runtimes, Delivery, and Quality Boundaries
Core implementation is TypeScript/Node.js; the site runs on Next.js/React with CSS/Tailwind-oriented registry output. Package libraries are bundled with tsup; Vitest is used across unit/integration/browser-oriented suites. GitHub Actions performs release, tests, browser tests, registry validation, and registry monitoring; Changesets drives package versioning.
- `apps/v4/package.json`
- `packages/shadcn/tsup.config.ts`
- `.github/workflows/validate-registries.yml`

Main entry points: [`apps/v4/app/layout.tsx`](https://github.com/shadcn-ui/ui/blob/main/apps/v4/app/layout.tsx) (Site shell), [`apps/v4/public/r/styles/default/index.json`](https://github.com/shadcn-ui/ui/blob/main/apps/v4/public/r/styles/default/index.json) (Published /r artifacts), [`packages/shadcn/src/commands/add.ts`](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/commands/add.ts) (Add command), [`packages/shadcn/src/utils/add-components.ts`](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/utils/add-components.ts) (Project mutator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_cli_entry{{"CLI dispatcher<br/>TypeScript CLI<br/>[index.ts]"}}
  node_add_command["Add command<br/>CLI command<br/>[add.ts]"]
  node_registry_resolver["Registry resolver<br/>registry client<br/>[resolver.ts]"]
  node_project_mutator["Project mutator<br/>mutation pipeline<br/>[add-components.ts]"]
  node_import_transform["Import transformer<br/>source transform"]
  node_template_generator["Template generator<br/>scaffolding<br/>[create-template.ts]"]
end

subgraph group_registry["Registry Distribution"]
  node_registry_manifest["Registry manifest<br/>registry definition<br/>[registry.json]"]
  node_registry_sources["Registry implementations<br/>registry source<br/>[registry.ts]"]
  node_registry_artifacts["Published /r artifacts<br/>static JSON<br/>[index.json]"]
end

subgraph group_site["Next.js Site"]
  node_site_shell["Site shell<br/>Next.js App Router<br/>[layout.tsx]"]
  node_docs_catalog["Docs and catalog<br/>MDX pages<br/>[page.tsx]"]
  node_docs_content["Docs metadata<br/>MDX content<br/>[meta.json]"]
  node_preview_routes["Isolated previews<br/>view route<br/>[page.tsx]"]
  node_design_tools["Create and typeset tools<br/>client experience<br/>[page.tsx]"]
  node_site_apis["Search and content APIs<br/>route handlers<br/>[route.ts]"]
  node_v0_integration["v0 initiation<br/>external integration route<br/>[route.ts]"]
end

subgraph group_packages["Reusable Packages"]
  node_react_primitives["React primitives<br/>React library<br/>[index.ts]"]
  node_framework_helpers["Framework helpers<br/>adapter library<br/>[index.ts]"]
end

subgraph group_delivery["Build and Delivery"]
  node_package_build["CLI package build<br/>tsup bundle<br/>[tsup.config.ts]"]
  node_registry_validation["Registry validation CI<br/>GitHub Actions"]
end

node_target_project["User project<br/>external repository"]

node_cli_entry -->|"dispatches"| node_add_command
node_add_command -->|"resolves requests"| node_registry_resolver
node_registry_resolver -->|"fetches"| node_registry_artifacts
node_add_command -->|"applies items"| node_project_mutator
node_project_mutator -->|"rewrites imports"| node_import_transform
node_project_mutator -->|"updates"| node_target_project
node_cli_entry -->|"scaffolds"| node_template_generator
node_template_generator -->|"creates starters"| node_target_project
node_registry_manifest -->|"indexes"| node_registry_sources
node_registry_sources -->|"builds"| node_registry_artifacts
node_site_shell -->|"renders"| node_docs_catalog
node_docs_content -->|"supplies content"| node_docs_catalog
node_site_shell -->|"links previews"| node_preview_routes
node_site_shell -->|"hosts"| node_design_tools
node_design_tools -->|"initiates"| node_v0_integration
node_site_shell -->|"serves"| node_site_apis
node_site_apis -->|"exposes"| node_registry_artifacts
node_site_shell -->|"publishes static output"| node_registry_artifacts
node_package_build -->|"bundles"| node_cli_entry
node_registry_validation -.->|"validates"| node_registry_manifest
node_registry_validation -.->|"checks output"| node_registry_artifacts

click node_cli_entry "https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/index.ts"
click node_add_command "https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/commands/add.ts"
click node_registry_resolver "https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/registry/resolver.ts"
click node_project_mutator "https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/utils/add-components.ts"
click node_import_transform "https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/utils/transformers/transform-import.ts"
click node_registry_manifest "https://github.com/shadcn-ui/ui/blob/main/apps/v4/registry.json"
click node_registry_sources "https://github.com/shadcn-ui/ui/blob/main/apps/v4/registry/bases/base/registry.ts"
click node_registry_artifacts "https://github.com/shadcn-ui/ui/blob/main/apps/v4/public/r/styles/default/index.json"
click node_site_shell "https://github.com/shadcn-ui/ui/blob/main/apps/v4/app/layout.tsx"
click node_docs_catalog "https://github.com/shadcn-ui/ui/blob/main/apps/v4/app/(app)/docs/%5B%5B...slug%5D%5D/page.tsx"
click node_docs_content "https://github.com/shadcn-ui/ui/blob/main/apps/v4/content/docs/components/meta.json"
click node_preview_routes "https://github.com/shadcn-ui/ui/blob/main/apps/v4/app/(view)/view/%5Bstyle%5D/%5Bname%5D/page.tsx"
click node_design_tools "https://github.com/shadcn-ui/ui/blob/main/apps/v4/app/(app)/(create)/create/page.tsx"
click node_site_apis "https://github.com/shadcn-ui/ui/blob/main/apps/v4/app/api/search/route.ts"
click node_v0_integration "https://github.com/shadcn-ui/ui/blob/main/apps/v4/app/(app)/(create)/init/v0/route.ts"
click node_react_primitives "https://github.com/shadcn-ui/ui/blob/main/packages/react/src/message-scroller/index.ts"
click node_framework_helpers "https://github.com/shadcn-ui/ui/blob/main/packages/helpers/src/core/index.ts"
click node_template_generator "https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/templates/create-template.ts"
click node_package_build "https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/tsup.config.ts"
click node_registry_validation "https://github.com/shadcn-ui/ui/blob/main/.github/workflows/validate-registries.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_entry,node_add_command,node_registry_resolver,node_project_mutator,node_import_transform,node_template_generator toneBlue
class node_registry_manifest,node_registry_sources,node_registry_artifacts toneAmber
class node_site_shell,node_docs_catalog,node_docs_content,node_preview_routes,node_design_tools,node_site_apis,node_v0_integration toneMint
class node_react_primitives,node_framework_helpers toneRose
class node_package_build,node_registry_validation toneIndigo
class node_target_project toneNeutral
```

## Components

### CLI

Consumer-facing project installation and mutation.

- [CLI dispatcher](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/index.ts): TypeScript CLI · Dispatches init, add, migration, registry, and MCP commands. · `packages/shadcn/src/index.ts`
- [Add command](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/commands/add.ts): CLI command · `packages/shadcn/src/commands/add.ts`
- [Registry resolver](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/registry/resolver.ts): registry client · Validates, fetches, and resolves registry dependencies and namespaces. · `packages/shadcn/src/registry/resolver.ts`
- [Project mutator](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/utils/add-components.ts): mutation pipeline · Detects target conventions and writes files, dependencies, CSS, fonts, and config safely. · `packages/shadcn/src/utils/add-components.ts`
- [Import transformer](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/utils/transformers/transform-import.ts): source transform · `packages/shadcn/src/utils/transformers/transform-import.ts`
- [Template generator](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/templates/create-template.ts): scaffolding · Creates framework and monorepo starter templates. · `packages/shadcn/src/templates/create-template.ts`

### Registry Distribution

Declarative content source and published artifacts.

- [Registry manifest](https://github.com/shadcn-ui/ui/blob/main/apps/v4/registry.json): registry definition · Defines components, blocks, hooks, styles, icons, and themes. · `apps/v4/registry.json`
- [Registry implementations](https://github.com/shadcn-ui/ui/blob/main/apps/v4/registry/bases/base/registry.ts): registry source · Implementation-base and style-specific item definitions. · `apps/v4/registry/bases/base/registry.ts`
- [Published /r artifacts](https://github.com/shadcn-ui/ui/blob/main/apps/v4/public/r/styles/default/index.json): static JSON · CLI-consumable registry output served by the site. · `apps/v4/public/r/styles/default/index.json`

### Next.js Site

Documentation, catalog, previews, and public APIs.

- [Site shell](https://github.com/shadcn-ui/ui/blob/main/apps/v4/app/layout.tsx): Next.js App Router · Public application layout and browsing entry point. · `apps/v4/app/layout.tsx`
- [Docs and catalog](https://github.com/shadcn-ui/ui/blob/main/apps/v4/app/(app)/docs/%5B%5B...slug%5D%5D/page.tsx): MDX pages · Documentation and component metadata drive catalog navigation. · `apps/v4/app/(app)/docs/[[...slug]]/page.tsx`
- [Docs metadata](https://github.com/shadcn-ui/ui/blob/main/apps/v4/content/docs/components/meta.json): MDX content · `apps/v4/content/docs/components/meta.json`
- [Isolated previews](https://github.com/shadcn-ui/ui/blob/main/apps/v4/app/(view)/view/%5Bstyle%5D/%5Bname%5D/page.tsx): view route · Renders component and example previews for embeds and catalog views. · `apps/v4/app/(view)/view/[style]/[name]/page.tsx`
- [Create and typeset tools](https://github.com/shadcn-ui/ui/blob/main/apps/v4/app/(app)/(create)/create/page.tsx): client experience · Stateful visual-system, preset, font, theme, and preview configuration. · `apps/v4/app/(app)/(create)/create/page.tsx`
- [Search and content APIs](https://github.com/shadcn-ui/ui/blob/main/apps/v4/app/api/search/route.ts): route handlers · Exposes search plus registry, LLM, RSS, Open Graph, and CSS endpoints. · `apps/v4/app/api/search/route.ts`
- [v0 initiation](https://github.com/shadcn-ui/ui/blob/main/apps/v4/app/(app)/(create)/init/v0/route.ts): external integration route · `apps/v4/app/(app)/(create)/init/v0/route.ts`

### Reusable Packages

- [React primitives](https://github.com/shadcn-ui/ui/blob/main/packages/react/src/message-scroller/index.ts): React library · Higher-level message scrolling and questionnaire primitives. · `packages/react/src/message-scroller/index.ts`
- [Framework helpers](https://github.com/shadcn-ui/ui/blob/main/packages/helpers/src/core/index.ts): adapter library · AI SDK and TanStack AI message/chat adapters. · `packages/helpers/src/core/index.ts`

### Build and Delivery

- [CLI package build](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/tsup.config.ts): tsup bundle · `packages/shadcn/tsup.config.ts`
- [Registry validation CI](https://github.com/shadcn-ui/ui/blob/main/.github/workflows/validate-registries.yml): GitHub Actions · Validates registry output during delivery. · `.github/workflows/validate-registries.yml`

### Other components

- **User project**: external repository · Arbitrary framework project receiving generated registry content.

## Connections

- CLI dispatcher → Add command: dispatches
- Add command → Registry resolver: resolves requests
- Registry resolver → Published /r artifacts: fetches
- Add command → Project mutator: applies items
- Project mutator → Import transformer: rewrites imports
- Project mutator → User project: updates
- CLI dispatcher → Template generator: scaffolds
- Template generator → User project: creates starters
- Registry manifest → Registry implementations: indexes
- Registry implementations → Published /r artifacts: builds
- Site shell → Docs and catalog: renders
- Docs metadata → Docs and catalog: supplies content
- Site shell → Isolated previews: links previews
- Site shell → Create and typeset tools: hosts
- Create and typeset tools → v0 initiation: initiates
- Site shell → Search and content APIs: serves
- Search and content APIs → Published /r artifacts: exposes
- Site shell → Published /r artifacts: publishes static output
- CLI package build → CLI dispatcher: bundles
- Registry validation CI → Registry manifest: validates
- Registry validation CI → Published /r artifacts: checks output
