Getting Started

本指南将带你完成搭建自己的组件注册库的过程。它默认你已经有一个包含组件的项目，并希望把它变成一个注册库。

如果你要从头开始一个新的注册库项目，可以把 registry template 作为起点。我们已经为你预先配置好了它。

要求

你可以自由设计和托管你的自定义注册库。唯一的要求是，注册库条目必须是符合 registry-item schema 规范 的有效 JSON 文件。

如果你想查看注册库示例，我们提供了一个可供你使用的 template project 作为起点。

registry.json

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

你的注册库必须在注册库端点的根目录下提供这个文件（或 JSON 载荷）。注册库端点就是你的注册库托管地址。

当你运行 build 命令时，shadcn CLI 会自动为你生成这个文件。

添加 registry.json 文件

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

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

这个 registry.json 文件必须符合 registry 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.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 是该文件的类型。

你可以在 registry item schema 文档 中阅读有关注册项 schema 和文件类型的更多信息。

构建你的注册库

安装 shadcn CLI

pnpmnpmyarnbun
pnpm add shadcn@latest
复制

添加构建脚本

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

Copy{
  "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 目录下，名称可以是你想要的任何内容。
• 注册项定义需要以下属性：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
复制

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