Docs
入门指南

入门指南

学习如何设置和运行您自己的组件注册中心。

本指南将带您了解设置自己的组件注册中心的过程。

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

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

registry.json

只有在使用 shadcn CLI 来构建您的注册中心时，才需要 registry.json 文件。

如果您使用其他构建系统，可以跳过此步骤，只要您的构建系统生成符合 registry-item 模式规范 的有效 JSON 文件即可。

添加 registry.json 文件

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

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

此 registry.json 文件必须符合 注册中心模式规范。

添加注册中心项目

创建您的组件

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

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

将您的组件添加到注册中心

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

registry.json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme",
  "homepage": "https://acme.com",
  "items": [
    {
      "name": "hello-world",
      "type": "registry:block",
      "title": "你好，世界",
      "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

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

pnpm add shadcn@canary

添加构建脚本

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

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

运行构建脚本

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

pnpm registry:build

提供您的注册中心

如果您在 Next.js 上运行注册中心，现在可以通过运行 next 服务器来提供注册中心。对于其他框架，命令可能会有所不同。

pnpm dev

您的文件现在将在 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。

pnpm dlx shadcn@latest add http://localhost:3000/r/hello-world.json
IntroductionOpen in v0