入门

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

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

要求

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

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

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@canary
Copy

添加构建脚本

在您的 package.json 文件中添加一个 registry:build 脚本。

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

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