文档
开始使用

开始使用

了解如何设置和运行您自己的组件注册表。

本指南将引导您完成设置您自己的组件注册表的过程。

它假设您已经有一个包含组件的项目，并且希望将其转换为注册表。

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

registry.json

只有当您使用 shadcn CLI 构建您的注册表时，才需要 registry.json 文件。

如果您使用不同的构建系统，您可以跳过此步骤，只要您的构建系统生成符合registry-item schema specification的有效 JSON 文件即可。

添加 registry.json 文件

在您的项目根目录中创建一个 registry.json 文件。您的项目可以是 Next.js、Remix、Vite 或任何其他支持 React 的项目。

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

此 registry.json 文件必须符合registry schema specification。

添加注册表项

创建您的组件

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

registry/new-york/hello-world/hello-world.tsx
import { Button } from "@/components/ui/button"
 
export function HelloWorld() {
  return <Button>Hello World</Button>
}
registry
└── new-york
    └── hello-world
        └── hello-world.tsx

将您的组件添加到注册表

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

registry.json
{
  "$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

注意：build 命令目前仅在 CLI 的 shadcn@canary 版本中可用。

pnpm add shadcn@canary

添加构建脚本

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

package.json
{
  "scripts": {
    "registry:build": "shadcn build"
  }
}

运行构建脚本

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

pnpm registry:build

服务您的注册表

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

pnpm dev

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

发布您的注册表

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

添加身份验证

shadcn CLI 不提供向您的注册表添加身份验证的内置方法。我们建议在您的注册表服务器上处理授权。

一种常见的简单方法是使用 token 查询参数来验证对您的注册表的请求。例如 https://127.0.0.1:3000/r/hello-world.json?token=[SECURE_TOKEN_HERE]。

使用安全令牌验证请求，如果令牌无效，则返回 401 未经授权的响应。shadcn CLI 和 Open in v0 都将处理 401 响应并向用户显示消息。

指南

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

  • 将您的注册表项放在 registry/[STYLE]/[NAME] 目录中。我使用 new-york 作为示例。它可以是您想要的任何内容，只要它嵌套在 registry 目录下即可。
  • 以下属性是区块定义所必需的：name、description、type 和 files。
  • 确保在 registryDependencies 中列出所有注册表依赖项。注册表依赖项是注册表中组件的名称，例如 input、button、card 等，或注册表项的 URL，例如 https://127.0.0.1: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。

pnpm dlx shadcn@latest add https://127.0.0.1:3000/r/hello-world.json
介绍示例