开始

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

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

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

registry.json

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

如果您使用的是不同的构建系统，只要您的构建系统生成符合注册表项 schema 规范的有效 JSON 文件，您就可以跳过此步骤。

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

添加注册表项

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

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

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"
        }
      ]
    }
  ]
}

构建您的注册表

pnpmnpmyarnbun
pnpm add shadcn@canary
Copy

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

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 来发布它。

添加认证

shadcn CLI 不提供内置的方式为您的注册表添加认证。我们建议在您的注册表服务器上处理授权。

一种常见的简单方法是使用token查询参数来认证对注册表的请求。例如http://localhost: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，例如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