本指南将引导您完成设置自己的组件注册表的过程。前提是您已经有一个包含组件的项目，并希望将其转换为注册表。

如果您要开始一个新的注册表项目，可以使用 注册表模板 作为起点。我们已为您配置好了相关设置。

要求

您可以根据需要自由设计和托管自定义注册表。唯一的要求是：注册表项必须是符合 注册表项架构规范 的有效 JSON 文件。

如果您想查看注册表示例，我们提供了一个 模板项目 供您参考。

registry.json

registry.json 是注册表的入口文件。它包含注册表的名称、主页，并定义了注册表中所有的项。

您的注册表必须在注册表端点的根目录下包含此文件（或 JSON 负载）。注册表端点是您托管注册表的 URL。

运行 build 命令时，shadcn 命令行工具会自动为您生成此文件。

添加 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 文件必须符合 注册表架构规范。

添加注册表项

创建组件

添加您的第一个组件。以下是一个简单的 <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": "一个简单的 Hello World 组件。",
      "files": [
        {
          "path": "registry/new-york/hello-world/hello-world.tsx",
          "type": "registry:component"
        }
      ]
    }
  ]
}

您需要通过添加 name（名称）、type（类型）、title（标题）、description（描述）和 files（文件）来定义注册表项。

对于添加的每个文件，必须指定 path（路径）和 type（类型）。path 是文件相对于项目根目录的相对路径，type 是文件的类型。

您可以在 注册表项架构文档 中了解更多关于注册表项架构和文件类型的信息。

构建注册表

安装 shadcn 命令行工具

npm install shadcn@canary

添加构建脚本

在 package.json 文件中添加 registry:build 脚本：

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

运行构建脚本

运行构建脚本以生成注册表 JSON 文件：

npm run registry:build

提供注册表服务

如果您在 Next.js 上运行注册表，现在可以通过运行 next 服务器来提供注册表服务。其他框架的命令可能有所不同：

npm run dev

您的文件现在将通过 http://localhost:3000/r/[名称].json 提供服务，例如 http://localhost:3000/r/hello-world.json。

发布注册表

要让其他开发者可以使用您的注册表，您可以通过将项目部署到公共 URL 来发布它。

指南

以下是构建注册表组件时应遵循的一些指南：

• 将注册表项放在 registry/[样式]/[名称] 目录中。我以 new-york 为例，您可以将其命名为任何名称，只要它嵌套在 registry 目录下即可。
• 块定义需要以下必填属性：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 目录中。

使用命令行工具安装

要使用 shadcn 命令行工具安装注册表项，请使用 add 命令，后跟注册表项的 URL：

npx shadcn@latest add http://localhost:3000/r/hello-world.json

有关如何从命名空间注册表安装注册表项的更多信息，请参见 命名空间注册表 文档。