shadcn-registries

配置 shadcn/ui 注册表、`components.json` 和 shadcn CLI（4.21.0）——涵盖默认的 `@shadcn` 注册表（Base UI、Radix 或 React Aria 样式，可通过 `init --base` 选择）、内置目录注册表（如 `@basecn`）、自定义命名空间注册表、GitHub 注册表（`owner/repo/item#ref`，公开和私有）以及注册表编写（`include`、`registry validate`、动态搜索）。

说明 components.json 架构（样式、Tailwind 配置路径、别名），并要求使用检测到的包管理器运行器（bunx/npx/pnpm dlx/yarn dlx）和 shadcn MCP 执行 CLI 命令，绝不手动复制组件。

shadcn 注册表

Agent 工作流（强制）

配置注册表之前，并行启动 Agent，每个 Agent 调用使用一个 name：

1. fuse-ai-pilot:explore-codebase - 查找现有的 components.json
2. fuse-ai-pilot:research-expert - 通过 Context7 验证最新的 CLI 选项

之后：运行 fuse-ai-pilot:sniper 进行验证。

---

概述

注册表	基元	样式
@shadcn（默认）	Base UI（自 2026-07-02 起为默认基元）	base-*（例如 base-nova）
@shadcn（默认）	Radix UI	radix-*（例如 radix-nova）；旧版 new-york（default 已弃用）
@shadcn（默认）	React Aria（自 2026-07-17 起）	aria-*
目录注册表（例如 @basecn，Base UI）	任意	CLI 内置，无需配置：add @basecn/<item>（列表：ui.shadcn.com/docs/directory）
自定义命名空间	任意	"registries": { "@acme": "https://.../{name}.json" } 或 registry add @acme=<url>
GitHub 注册表	任意	add owner/repo/item[#ref]，根目录中的 registry.json，无需服务器/构建

样式：{base}-{style}，其中 base = base、radix、aria，style = vega、nova、maia、lyra、mira、luma、sera、rhea（架构：https://ui.shadcn.com/schema.json）。初始化后无法更改样式；请改用 apply --preset 切换设计。

---

关键规则

1. 务必先检测包管理器（使用 {runner}），再运行任何 CLI 命令
2. 添加组件前务必查阅 MCP
3. 同一项目中绝不混用组件基元（Base UI / Radix / React Aria）
4. 确保 components.json 与实际基元保持同步
5. 添加组件时使用 CLI，绝不手动复制
6. 安装前审查第三方条目：view <item>、add <item> --dry-run|--diff|--view；将 GitHub 条目固定到标签或完整 SHA

---

架构

project/
├── components.json         # shadcn/ui configuration
├── components/ui/          # Generated components (import { cn } from "cn")
└── lib/utils.ts            # export { cn } from "cn"  (since Sept 2026; `migrate cn` for older projects)

-> 完整设置说明请参阅 registry-setup.md

---

CLI 命令

务必使用检测到的包管理器（先运行 shadcn-detection）。 {runner} = bunx | npx | pnpm dlx | yarn dlx

# Initialize (alias: create). Default base = base (Base UI)
{runner} shadcn@latest init
{runner} shadcn@latest init -b radix          # -b base | radix | aria (add -b radix in CI that expects Radix)
{runner} shadcn@latest init -t vite           # -t next | start | vite | react-router | laravel | astro
{runner} shadcn@latest init --preset b2D0vQ7G4 --rtl --pointer --monorepo
{runner} shadcn@latest init --defaults        # = --template=next + "nova" preset on the default base -> style base-nova

# Add components (resolved for the style in components.json)
{runner} shadcn@latest add button dialog select
{runner} shadcn@latest add button --dry-run   # also --diff [path] (replaces deprecated `diff`), --view [path]
{runner} shadcn@latest add @basecn/button     # directory registry, no config needed
{runner} shadcn@latest add acme/toolkit/auth-kit#v1.0.0   # GitHub registry item

# Presets and existing projects
{runner} shadcn@latest apply --preset b2D0vQ7G4 [--only theme,font]   # keeps base + RTL
{runner} shadcn@latest preset decode|resolve|url|open <code>
{runner} shadcn@latest info --json            # framework, base, style, aliases, installed components
{runner} shadcn@latest docs combobox --base aria   # docs/examples/API links per base

# Discovery
{runner} shadcn@latest search @shadcn -q button -t ui --json   # alias: list; no arg = all configured registries
{runner} shadcn@latest view @acme/auth acme/toolkit/item

# Maintenance
{runner} shadcn@latest migrate cn|icons|base-color|radix|rtl [path]   # --list, --from, --to
{runner} shadcn@latest eject                  # inline shadcn/tailwind.css, drop the shadcn dependency (irreversible)
{runner} shadcn@latest mcp init --client claude   # claude | cursor | vscode | codex | opencode

# Registry authoring
{runner} shadcn@latest build [./registry.json] -o ./public/r
{runner} shadcn@latest registry validate [./registry.json | owner/repo#ref]
{runner} shadcn@latest registry add @acme=https://acme.com/r/{name}.json

以上标志来自 npx [email protected] <cmd> --help（2026-09-27）。详情和来源：registry-config.md。

MCP（强制）

mcp__shadcn__search_items_in_registries -> find component
mcp__shadcn__get_add_command_for_items  -> get exact CLI command

---

components.json 结构

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-nova",
  "rsc": true,
  "tailwind": { "config": "", "css": "app/globals.css", "baseColor": "neutral", "cssVariables": true },
  "aliases": { "components": "@/components", "utils": "@/lib/utils" }
}

架构要求的键：style、tailwind（config、css、baseColor、cssVariables）、rsc、aliases（utils、components）。别名也可以是 package.json#imports 说明符（#components、#lib/utils）。

-> 完整架构请参阅 registry-config.md

---

参考指南

概念

主题	参考文档	查阅时机
注册表配置	registry-config.md	设置 components.json

模板

模板	使用场景
registry-setup.md	项目初始设置

---

最佳实践

应做事项

• 添加前使用 MCP 检查注册表
• 确保 components.json 与实际基元保持同步
• 添加组件时使用 CLI，而非手动复制

不要

• 在同一项目中混用组件基础库（Radix Combobox 依赖 @base-ui/react 是预期行为，不属于混用）
• 未检查注册表源代码就修改组件内部实现
• 跳过 components.json 配置
• 在发布的说明中安装未锁定版本的第三方 GitHub 项目