Introducing a new way to review your PRs.

Read the announcement

shadcn-ui / ui

Composable, accessible components with thoughtful defaults. Build your own component library with code you can customize, extend, and make your own.

View on GitHub

13 documents · Updated Nov 16, 2026

overview

Knowledge Base updated: 2026-11-16

Knowledge Base Index

1. Orientation

This repository is the shadcn-ui/ui monorepo: it contains the public shadcn CLI, registry tooling, the v4 documentation/registry site, published helper packages, templates, and integration test infrastructure. The highest-level flow is: registry content and project metadata are resolved, transformed, and installed by the CLI into consumer applications.

Main parts:

  • apps/v4 — Next.js documentation site, component previews, registry catalog, and registry build scripts.
  • packages/shadcn — user-facing CLI commands plus preflights, migrations, MCP support, templates, styles, and utilities.
  • packages/registry — registry resolution, validation, project detection, transformations, and install/update machinery.
  • packages/react and packages/helpers — published runtime/UI helper packages.
  • templates, skills, packages/tests, and root config — workspace infrastructure, starter templates, skill assets, and integration tests.

Critical state is primarily filesystem-backed:

  • Registry/catalog state lives in apps/v4/registry/**, apps/…/registry.json, and registry metadata generated or consumed by packages/registry/**.
  • Consumer project configuration is represented through files such as components.json, Tailwind/CSS files, package manifests, env files, and aliases handled by packages/registry and packages/shadcn.
  • There is no repository-owned database or queue; external interactions are mostly package managers, GitHub/registry sources, local files, and the Next.js app runtime.

2. Architecture diagrams

flowchart TD
  subgraph App[apps/v4]
    Site[Next.js docs site]
    UI[site components]
    Catalog[v4 registry catalog]
    SiteScripts[registry build scripts]
  end

  subgraph CLI[packages/shadcn]
    Commands[CLI commands]
    Support[preflights migrations utils]
    MCP[MCP server]
  end

  subgraph Registry[packages/registry]
    Core[registry core]
    Detect[project detection]
    Transform[transformers codemod]
    Update[install updaters]
  end

  subgraph Published[Published helpers]
    ReactPkg[packages/react]
    HelpersPkg[packages/helpers]
  end

  subgraph Infra[Repo infrastructure]
    Templates[templates]
    Tests[packages/tests]
    Workspace[root pnpm turbo vitest config]
  end

  Site --> UI
  Site --> Catalog
  SiteScripts --> Catalog
  Commands --> Support
  Commands --> Core
  Commands --> Detect
  Commands --> Transform
  Commands --> Update
  Commands --> MCP
  Core --> Catalog
  Update --> Templates
  Tests --> Commands
  Tests --> Registry
  Workspace --> App
  Workspace --> CLI
  Workspace --> Registry
  Workspace --> Published
flowchart LR
  User[user runs shadcn CLI] --> Cmd[packages/shadcn commands]
  Cmd --> Preflight[preflights and project checks]
  Preflight --> Detect[packages/registry project detection]
  Cmd --> Resolve[registry source resolution]
  Resolve --> Transform[registry transformers]
  Transform --> Update[install updaters]
  Update --> Files[consumer files CSS deps env config]
flowchart TD
  RegistryFiles[apps/v4/registry files] --> BuildScripts[apps/v4/scripts build/capture/validate]
  BuildScripts --> RegistryJson[apps/v4/registry.json and generated indexes]
  RegistryJson --> SiteLib[apps/v4/lib registry helpers]
  SiteLib --> Pages[apps/v4 app routes]
  Pages --> Preview[components previews blocks charts]
flowchart LR
  Request[docs site request] --> Route[apps/v4/app route]
  Route --> Source[content/source config]
  Source --> MDX[MDX components]
  Route --> Lib[apps/v4/lib helpers]
  Lib --> RegistryData[registry docs blocks components]
  MDX --> UI[apps/v4/components]
  UI --> Response[rendered page or API response]

3. Glossary

  • Registry item — a shadcn component/block/style/resource definition that can be resolved, transformed, displayed, or installed.
  • components.json — consumer-project configuration file used by the CLI and registry helpers to understand aliases, style, and target paths.
  • Preflight — CLI validation/setup step under packages/shadcn/src/preflights/** that checks project state before mutating files.
  • MCP — Model Context Protocol support implemented by packages/shadcn/src/mcp/** and exposed through the CLI.
  • v4 app — the apps/v4 Next.js documentation and registry catalog application.

4. Codebase-wide invariants

  • The repo is organized as a pnpm monorepo with package/app membership declared in pnpm-workspace.yaml and coordinated by root package.json and turbo.json.
  • Package-level TypeScript builds use per-package build/test config files; representative examples are packages/…/tsup.config.ts, packages/…/tsup.config.ts, packages/…/tsup.config.ts, and their vitest.config.ts files.
  • Tests are colocated with implementation in the main packages using *.test.ts naming, as seen under packages/shadcn/src/**, packages/registry/src/**, and apps/…/*.test.ts.
  • Registry installation behavior is split between resolution/metadata code and mutation code: resolution lives under packages/registry/src/registry/**, while project mutations live under packages/registry/src/updaters/** and packages/…/add-components.ts.
  • The v4 site keeps route/content concerns separate from reusable UI: routes and content live under apps/v4/app/** and apps/v4/content/**, while reusable display/navigation components live under apps/v4/components/**.

5. Routing table