快速上手

本文将带你一步步搭建组件注册表。假设你已经拥有包含组件的项目，并希望将其转化为注册表。

如果要从零开始，可以使用我们准备好的 注册表模板 作为起点，基础配置都已设置完毕。

前置要求

你可以按照自己的需求设计并部署注册表。唯一的要求是注册表条目必须是符合 注册表条目 Schema 规范 的合法 JSON 文件。

想了解注册表的结构示例，可以参考我们的 模板项目。

registry.json

registry.json 是注册表的入口文件，包含注册表名称、主页地址以及所有条目的定义。

注册表必须在服务端点根路径提供这个文件（或返回相同结构的 JSON）。端点就是你托管注册表的 URL。

运行 build 命令时，shadcn CLI 会自动生成该文件。

新建 registry.json 文件

在项目根目录创建 registry.json。无论是 Next.js、Vite、Vue、Svelte、PHP 还是其他框架，只要能通过 HTTP 提供 JSON 即可。

复制{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme",
  "homepage": "https://acme.com",
  "items": [
    // ...
  ]
}

该 registry.json 文件必须符合 registry.json Schema 定义。

添加注册表条目

创建组件

先添加一个组件。下面是一个简单的 <HelloWorld /> 示例：

复制import { Button } from "@/components/ui/button"
 
export function HelloWorld() {
  return <Button>Hello World</Button>
}

复制registry
└── new-york
    └── hello-world
        └── hello-world.tsx

将组件加入注册表

要把组件纳入注册表，需要在 registry.json 中添加对应的定义。

复制{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme",
  "homepage": "https://acme.com",
  "items": [
    {
      "name": "hello-world",
      "type": "registry:block",
      "title": "Hello World",
      "description": "A simple hello world component.",
      "files": [
        {
          "path": "registry/new-york/hello-world/hello-world.tsx",
          "type": "registry:component"
        }
      ]
    }
  ]
}

在定义条目时，需要提供 name、type、title、description 以及 files。

为每个文件指定 path 与 type。path 是相对于项目根目录的路径，type 则表示文件类型。

想了解条目 Schema 与文件类型，可查阅 注册表条目文档。

构建注册表

安装 shadcn CLI

pnpmnpmyarnbun
pnpm add shadcn@latest
复制

添加构建脚本

在 package.json 中新增 registry:build 脚本。

复制{
  "scripts": {
    "registry:build": "shadcn build"
  }
}

执行构建脚本

运行该脚本生成注册表 JSON 文件。

pnpmnpmyarnbun
pnpm registry:build
复制

启动注册表服务

如果注册表托管在 Next.js 中，只需运行 next 服务即可。其他框架可根据自身命令启动。

pnpmnpmyarnbun
pnpm dev
复制

此时即可通过 http://localhost:3000/r/[NAME].json 访问，例如 http://localhost:3000/r/hello-world.json。

发布注册表

想让其他开发者使用，直接将项目部署到公开访问的 URL 即可。

编写规范

编写注册表组件时，可参考以下建议：

• 将条目放在 registry/[STYLE]/[NAME] 目录下。文中示例使用 new-york，你也可以自定义，只要位于 registry 目录即可。
• Blocks 定义必须包含：name、description、type、files。
• 建议为条目提供清晰的名称与描述，便于 LLM 理解组件用途。
• 确保在 registryDependencies 中列出所有注册表依赖。依赖可以是注册表内的组件名称（如 input、button、card），也可以是注册表 URL（如 http://localhost:3000/r/editor.json）。
• 在 dependencies 中列出所有包依赖。依赖应使用包名（如 zod、sonner），需要指定版本时可使用 name@version 格式，例如 zod@^3.20.0。
• 导入路径应统一使用 @/registry。 例如：import { HelloWorld } from "@/registry/new-york/hello-world/hello-world"
• 建议将条目中的文件组织在 components、hooks、lib 等目录下，保持结构清晰。

通过 CLI 安装

若要使用 shadcn CLI 安装注册表条目，执行 add 命令并传入条目 URL。

pnpmnpmyarnbun
pnpm dlx shadcn@latest add http://localhost:3000/r/hello-world.json
复制

关于命名空间注册表的安装方式，可查阅命名空间注册表文档。