概述

相关源文件

• apps/v4/package.json
• apps/www/package.json
• apps/www/tsconfig.json
• package.json
• packages/cli/CHANGELOG.md
• packages/cli/package.json
• packages/shadcn/CHANGELOG.md
• packages/shadcn/package.json
• pnpm-lock.yaml
• prettier.config.cjs

本文档全面概述了 shadcn-ui 存储库，这是一个组件系统，提供可直接复制粘贴的 UI 组件，而非传统的 npm 包。该系统包含一个单体仓库，其中有文档网站、用于组件管理的 CLI 工具以及基于注册表的发行系统。

有关 CLI 工具功能的详细信息，请参阅 CLI 工具。有关组件库的详细信息，请参阅 组件系统。有关构建和发行流程的信息，请参阅 构建与发行。

什么是 shadcn/ui

shadcn/ui 是一个在根本上不同于传统组件库的组件系统。开发者不是将组件安装为 npm 依赖项，而是将实际源代码直接复制到他们的项目中。这种方法提供了几个优点：

• 完全拥有权：组件成为您代码库的一部分
• 完全可定制：没有抽象障碍阻止修改
• 无依赖锁定：组件独立于库更新运行
• Tailwind CSS 集成：专为基于 Tailwind 的项目构建

该系统建立在 Radix UI 原语之上，以实现可访问性和功能性，并使用 Tailwind CSS 进行样式设计，通过基于 Web 的注册表进行分发。

来源： packages/shadcn/package.json1-99 packages/cli/CHANGELOG.md1-6 packages/shadcn/CHANGELOG.md1-10

Monorepo 架构

该单体仓库使用 pnpm 和 workspace 配置，并使用 Turborepo 进行构建编排。

包管理

该单体仓库使用 pnpm 和 workspace 配置，并使用 Turborepo 进行构建编排。

工具	目的	配置
pnpm	包管理器	package.json51
turbo	构建编排	package.json16-49
工作区	单体仓库结构	package.json11-14

来源： package.json1-90 pnpm-lock.yaml1-114

核心应用

文档网站 (apps/www)

主要的文档网站，使用 Next.js 和 Contentlayer 构建。

关键脚本和功能

• dev：开发服务器，端口 3333
• build:registry：生成组件注册表 JSON 文件
• registry:capture：组件文档的截图

下一代网站 (apps/v4)

下一代文档站点，具有增强功能

• 框架：Next.js 15.3.1，React 19
• 端口: 4000
• 文档：基于 Fumadocs 的系统
• 样式：Tailwind CSS v4，增强型 PostCSS

与 apps/www 的主要区别

• 对现代 React 19 的支持
• Tailwind CSS v4 集成
• Fumadocs 文档框架
• 增强的注册表构建系统

来源： apps/www/package.json1-128 apps/v4/package.json1-154

CLI 工具系统

当前 CLI (packages/shadcn)

当前 CLI 工具分发为 shadcn npm 包

主要功能

• 包名：shadcn (v2.6.0)
• 分发：带二进制文件的 npm 包
• 注册表 URL：可通过环境变量配置
• 命令：init、add、registry:build

已弃用的 CLI (packages/cli)

为兼容性维护的旧版 CLI 工具

• 包名：shadcn-ui (v0.9.5)
• 状态：已弃用，附带迁移通知
• 维护：仅安全更新

来源： packages/shadcn/package.json1-99 packages/cli/package.json1-46 packages/shadcn/CHANGELOG.md3-10

组件分发模型

shadcn/ui 系统使用独特的基于注册表的发行模式。

注册表构建流程

注册表生成过程将源代码组件转换为可发行的 JSON。

1. 源文件收集：组件存储在 apps/www/registry/ 和 apps/v4/registry/ 中
2. 构建处理：build-registry.mts 脚本处理组件文件
3. JSON 生成：元数据和代码存储在 public/r/styles/ 目录中
4. 索引创建：__registry__/index.tsx 提供组件目录

组件安装流程

当用户运行 shadcn add <component> 时

1. CLI 从注册表 JSON 中获取组件元数据
2. 组件源代码被下载并处理
3. 文件被直接写入用户的项目结构
4. 通过包管理器自动安装依赖项
5. CSS 变量和配置被更新

来源： apps/www/package.json9-11 apps/v4/package.json15-16 packages/shadcn/package.json49-50

技术栈

前端依赖

类别	包	版本	目的
框架	next	14.3.0/15.3.1	React 框架
UI 原语	@radix-ui/*	最新版	可访问组件
样式	tailwindcss	3.4.6/4.1.8	实用 CSS
图标	lucide-react	0.474.0/0.477.0	图标库
状态管理	jotai	2.1.0+	状态管理
表单	react-hook-form	7.54.2	表单处理

构建工具

工具	目的	配置
typescript	类型检查	多个版本（4.9.5-5.7.3）
eslint	代码 Linting	package.json64-69
prettier	格式化	prettier.config.cjs1-36
tsup	包构建	CLI 包
contentlayer2	MDX 处理	文档网站

开发工作流

该仓库支持多种开发环境

来源： pnpm-lock.yaml115-397 package.json15-49 apps/www/package.json22-99 apps/v4/package.json19-95