入门指南

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

如果你是从头开始创建一个新的注册表项目，可以使用注册表模板作为起点。我们已经为你做好了配置。

要求

你可以根据自己的需求设计并托管自定义注册表。唯一的要求是你的注册表项目必须是符合注册表条目模式规范的有效 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.com/schema/registry.json",
  "name": "acme",
  "homepage": "https://acme.com",
  "items": [
    // ...
  ]
}

该 registry.json 文件必须符合注册表模式规范。

添加一个注册表条目

创建你的组件

添加你的第一个组件。下面是一个简单的 <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": "一个简单的 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 CLI

pnpmnpmyarnbun
pnpm add shadcn@latest
Copy

添加构建脚本

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

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

运行构建脚本

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

pnpmnpmyarnbun
pnpm registry:build
Copy

提供你的注册表服务

如果你在使用 Next.js 运行注册表，可以通过启动 next 服务器来提供服务。其他框架启动命令可能不同。

pnpmnpmyarnbun
pnpm dev
Copy

你的文件现在将通过 http://localhost:3000/r/[NAME].json 访问，例如 http://localhost:3000/r/hello-world.json。

发布你的注册表

为了让其他开发者访问你的注册表，你可以将项目部署到一个公开的 URL。

指南

构建注册表组件时，请遵循以下指南：

• 将注册表条目放在 registry/[STYLE]/[NAME] 目录下。示例中使用了 new-york，你可以根据需要选择任何名称，只要它位于 registry 目录下。
• 块定义中必需的属性有：name、description、type 和 files。
• 推荐为注册表条目添加合适的名称和描述，这有助于大型语言模型理解该组件及其用途。
• 确保在 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
Copy

有关如何从命名空间注册表安装条目的详细信息，请参阅带命名空间的注册表文档。