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/reactandpackages/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 bypackages/registry/**. - Consumer project configuration is represented through files such as components.json, Tailwind/CSS files, package manifests, env files, and aliases handled by
packages/registryandpackages/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/v4Next.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 underpackages/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/**andapps/v4/content/**, while reusable display/navigation components live underapps/v4/components/**.
5. Routing table
-
apps/v4/app/**-> docs/apps-v4-site-routing-content.md -
apps/v4/content/**-> docs/apps-v4-site-routing-content.md -
apps/…/source.config.ts -> docs/apps-v4-site-routing-content.md
-
apps/…/mdx-components.tsx -> docs/apps-v4-site-routing-content.md
-
apps/…/next.config.mjs -> docs/apps-v4-site-routing-content.md
-
apps/…/components.json -> docs/apps-v4-site-routing-content.md
-
apps/…/tsconfig.json -> docs/apps-v4-site-routing-content.md
-
apps/…/tsconfig.scripts.json -> docs/apps-v4-site-routing-content.md
-
any change to v4 docs routing, MDX rendering, RSS, sitemap, OG, robots, or app API routes -> docs/apps-v4-site-routing-content.md
-
apps/v4/components/**-> docs/apps-v4-components-ui.md -
apps/v4/hooks/**-> docs/apps-v4-components-ui.md -
apps/v4/styles/**-> docs/apps-v4-components-ui.md -
apps/v4/public/**-> docs/apps-v4-components-ui.md -
any change to v4 navigation, preview, block/chart display, theme switching, or shared UI components -> docs/apps-v4-components-ui.md
-
apps/v4/registry/**-> docs/apps-v4-registry-catalog-build.md -
apps/…/registry.json -> docs/apps-v4-registry-catalog-build.md
-
apps/v4/scripts/**-> docs/apps-v4-registry-catalog-build.md -
apps/v4/lib/registry**-> docs/apps-v4-registry-catalog-build.md -
apps/v4/lib/registry-health/**-> docs/apps-v4-registry-catalog-build.md -
apps/…/components.ts -> docs/apps-v4-registry-catalog-build.md
-
apps/…/categories.ts -> docs/apps-v4-registry-catalog-build.md
-
apps/…/font-definitions.ts -> docs/apps-v4-registry-catalog-build.md
-
apps/…/registry-directory.ts -> docs/apps-v4-registry-catalog-build.md
-
any change to v4 registry generation, catalog metadata, blocks, themes, colors, fonts, or registry validation scripts -> docs/apps-v4-registry-catalog-build.md
-
packages/shadcn/src/commands/**-> docs/shadcn-cli-commands.md -
any change to a user-facing
shadcnCLI command or command registration -> docs/shadcn-cli-commands.md -
packages/shadcn/src/preflights/**-> docs/shadcn-cli-support-workflows.md -
packages/shadcn/src/migrations/**-> docs/shadcn-cli-support-workflows.md -
packages/shadcn/src/utils/**-> docs/shadcn-cli-support-workflows.md -
packages/shadcn/src/preset/**-> docs/shadcn-cli-support-workflows.md -
packages/shadcn/src/registry/**-> docs/shadcn-cli-support-workflows.md -
packages/shadcn/src/schema/**-> docs/shadcn-cli-support-workflows.md -
packages/shadcn/src/styles/**-> docs/shadcn-cli-support-workflows.md -
packages/shadcn/src/templates/**-> docs/shadcn-cli-support-workflows.md -
packages/shadcn/src/icons/**-> docs/shadcn-cli-support-workflows.md -
packages/…/colors.ts -> docs/shadcn-cli-support-workflows.md
-
packages/…/tailwind.css -> docs/shadcn-cli-support-workflows.md
-
packages/shadcn/src/test-helpers/**-> docs/shadcn-cli-support-workflows.md -
any change to CLI preflight checks, migrations, scaffolding, dry-run formatting, templates, styles, presets, or schema helpers -> docs/shadcn-cli-support-workflows.md
-
packages/shadcn/src/mcp/**-> docs/shadcn-mcp-server.md -
any change to MCP server tools/resources or MCP CLI wiring -> docs/shadcn-mcp-server.md
-
packages/registry/src/registry/**-> docs/registry-core-resolution.md -
packages/registry/src/schema/**-> docs/registry-core-resolution.md -
packages/…/json-config.ts -> docs/registry-core-resolution.md
-
packages/…/highlighter.ts -> docs/registry-core-resolution.md
-
packages/…/tsup.config.ts -> docs/registry-core-resolution.md
-
packages/…/vitest.config.ts -> docs/registry-core-resolution.md
-
packages/…/vitest.alias.ts -> docs/registry-core-resolution.md
-
any change to registry source addressing, fetching, parsing, resolving, validation, namespaces, GitHub sources, proxies, auth, or registry errors -> docs/registry-core-resolution.md
-
packages/…/frameworks.ts -> docs/registry-project-detection-config.md
-
packages/…/get-config.ts -> docs/registry-project-detection-config.md
-
packages/…/get-monorepo-info.ts -> docs/registry-project-detection-config.md
-
packages/…/get-package-info.ts -> docs/registry-project-detection-config.md
-
packages/…/get-package-manager.ts -> docs/registry-project-detection-config.md
-
packages/…/get-project-info.ts -> docs/registry-project-detection-config.md
-
packages/…/workspace.ts -> docs/registry-project-detection-config.md
-
packages/…/env-helpers.ts -> docs/registry-project-detection-config.md
-
packages/…/env-loader.ts -> docs/registry-project-detection-config.md
-
packages/…/import-matcher.ts -> docs/registry-project-detection-config.md
-
packages/…/package-imports.ts -> docs/registry-project-detection-config.md
-
packages/…/resolve-file-path.ts -> docs/registry-project-detection-config.md
-
packages/…/resolve-import.ts -> docs/registry-project-detection-config.md
-
packages/…/is-safe-target.ts -> docs/registry-project-detection-config.md
-
packages/…/target-aliases.ts -> docs/registry-project-detection-config.md
-
packages/…/tailwind-theme-colors.ts -> docs/registry-project-detection-config.md
-
packages/…/font-markers.ts -> docs/registry-project-detection-config.md
-
packages/registry/src/icons/**-> docs/registry-project-detection-config.md -
packages/registry/src/test-helpers/**-> docs/registry-project-detection-config.md -
any change to project/framework/package-manager/workspace detection, alias/import resolution, env loading, or target path safety -> docs/registry-project-detection-config.md
-
packages/registry/src/transformers/**-> docs/registry-transformers-codemod.md -
packages/registry/src/codemod/**-> docs/registry-transformers-codemod.md -
any change to registry item code transforms, AST/text edit helpers, imports, JSX transforms, icon transforms, CSS variable transforms, Tailwind prefixing, RSC, fonts, Next.js transforms, RTL, or cleanup -> docs/registry-transformers-codemod.md
-
packages/…/add-components.ts -> docs/registry-install-updaters.md
-
packages/registry/src/updaters/**-> docs/registry-install-updaters.md -
packages/registry/src/preset/**-> docs/registry-install-updaters.md -
any change to add/install flow, file updates, CSS updates, dependency updates, env updates, font updates, Tailwind config updates, or presets -> docs/registry-install-updaters.md
-
packages/react/**-> docs/react-and-helpers-packages.md -
packages/helpers/**-> docs/react-and-helpers-packages.md -
any change to published React runtime utilities, message scroller, questionnaire, render hooks, AI helpers, core helpers, or TanStack AI helpers -> docs/react-and-helpers-packages.md
-
pnpm-workspace.yaml -> docs/repo-templates-tests-infrastructure.md
-
pnpm-lock.yaml -> docs/repo-templates-tests-infrastructure.md
-
tsconfig.json -> docs/repo-templates-tests-infrastructure.md
-
vitest.config.ts -> docs/repo-templates-tests-infrastructure.md
-
vitest.workspace.ts -> docs/repo-templates-tests-infrastructure.md
-
.changeset/**-> docs/repo-templates-tests-infrastructure.md -
.github/**-> docs/repo-templates-tests-infrastructure.md -
.cursor-plugin/**-> docs/repo-templates-tests-infrastructure.md -
.claude/**-> docs/repo-templates-tests-infrastructure.md -
.vscode/**-> docs/repo-templates-tests-infrastructure.md -
.commitlintrc.json -> docs/repo-templates-tests-infrastructure.md
-
.editorconfig-> docs/repo-templates-tests-infrastructure.md -
.eslintignore-> docs/repo-templates-tests-infrastructure.md -
.eslintrc.json -> docs/repo-templates-tests-infrastructure.md
-
.prettierignore-> docs/repo-templates-tests-infrastructure.md -
prettier.config.cjs -> docs/repo-templates-tests-infrastructure.md
-
scripts/**-> docs/repo-templates-tests-infrastructure.md -
templates/**-> docs/repo-templates-tests-infrastructure.md -
skills/**-> docs/repo-templates-tests-infrastructure.md -
packages/tests/**-> docs/repo-templates-tests-infrastructure.md -
CONTRIBUTING.md -> docs/repo-templates-tests-infrastructure.md
-
any change to workspace tooling, package manager configuration, release metadata, GitHub automation, app templates, skills, or integration test harnesses -> docs/repo-templates-tests-infrastructure.md