入门

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

如果您正在启动一个全新的注册表项目，可以使用 注册表模板 作为起点。我们已经为您配置好了。

要求

您可以按照自己认为合适的方式设计和托管自定义注册表。唯一的要求是，您的注册表项必须是符合 注册表项 schema 规范 的有效 JSON 文件。

如果您想查看注册表的示例，我们有一个 模板项目 可供您作为起点使用。

registry.json

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

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

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

添加 registry.json 文件

在项目根目录中创建一个 registry.json 文件。您的项目可以是 Next.js、Vite、Vue、Svelte、PHP 或任何其他框架，只要它支持通过 HTTP 提供 JSON 服务即可。

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

此 registry.json 文件必须符合 注册表 schema 规范。

添加注册表项

创建您的组件

添加您的第一个组件。以下是一个简单的 <HelloWorld /> 组件示例

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

Copyregistry
└── new-york
    └── hello-world
        └── hello-world.tsx

将组件添加到注册表

要将组件添加到注册表，您需要将组件定义添加到 registry.json 中。

Copy{
  "$schema": "https://ui.shadcn.org.cn/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 文档 中详细了解注册表项 schema 和文件类型。

构建您的注册表

安装 shadcn CLI

pnpmnpmyarnbun
pnpm add shadcn@latest
Copy

添加构建脚本

将 registry:build 脚本添加到您的 package.json 文件中。

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

运行构建脚本

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

pnpmnpmyarnbun
pnpm registry:build
Copy

托管您的注册表

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

pnpmnpmyarnbun
pnpm dev
Copy

您的文件现在将在 https://:3000/r/[NAME].json 处提供，例如 https://:3000/r/hello-world.json。

发布您的注册表

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

准则

以下是为注册表构建组件时需要遵循的一些准则。

• 将您的注册表项放置在 registry/[STYLE]/[NAME] 目录中。我以 new-york 为例。只要嵌套在 registry 目录下，它可以是任何您想要的名称。
• 区块定义需要以下属性：name、description、type 和 files。
• 建议为您的注册表项添加合适的名称和描述。这有助于 LLM 理解组件及其用途。
• 请确保在 registryDependencies 中列出所有注册表依赖项。注册表依赖项是注册表中组件的名称，例如 input、button、card 等，或者是指向注册表项的 URL，例如 https://: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 https://:3000/r/hello-world.json
Copy

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