入门

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

🌐 This guide will walk you through the process of setting up your own component registry. It assumes you already have a project with components and would like to turn it into a registry.

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

🌐 If you're starting a new registry project, you can use the registry template as a starting point. We have already configured it for you.

要求

🌐 Requirements

你可以自由设计和托管你的自定义注册表，按你认为合适的方式进行。唯一的要求是，你的注册表条目必须是符合 registry-item schema specification 的有效 JSON 文件。

🌐 You are free to design and host your custom registry as you see fit. The only requirement is that your registry items must be valid JSON files that conform to the registry-item schema specification.

如果你想查看一个注册表的示例，我们有一个模板项目供你用作起点。

🌐 If you'd like to see an example of a registry, we have a template project for you to use as a starting point.

registry.json

registry.json 是注册表的入口点。它包含注册表的名称、主页，并定义注册表中存在的所有项目。

🌐 The registry.json is the entry point for the registry. It contains the registry's name, homepage, and defines all the items present in the registry.

你的注册表必须在注册表端点的根目录中包含此文件（或 JSON 有效负载）。注册表端点是你的注册表托管的 URL。

🌐 Your registry must have this file (or JSON payload) present at the root of the registry endpoint. The registry endpoint is the URL where your registry is hosted.

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

🌐 The shadcn CLI will automatically generate this file for you when you run the build command.

添加一个 registry.json 文件

🌐 Add a registry.json file

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

🌐 Create a registry.json file in the root of your project. Your project can be a Next.js, Vite, Vue, Svelte, PHP or any other framework as long as it supports serving JSON over HTTP.

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

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

🌐 This registry.json file must conform to the registry schema specification.

添加一个注册表项

🌐 Add a registry item

创建你的组件

🌐 Create your component

添加你的第一个组件。这里有一个简单的 <HelloWorld /> 组件示例：

🌐 Add your first component. Here's an example of a simple <HelloWorld /> component:

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

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

将你的组件添加到注册表

🌐 Add your component to the registry

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

🌐 To add your component to the registry, you need to add your component definition to registry.json.

Copy{
  "$schema": "https://shadcn.nodejs.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 来定义你的注册表项。

🌐 You define your registry item by adding a name, type, title, description and files.

对于你添加的每个文件，你必须指定该文件的 path 和 type。path 是从项目根目录到该文件的相对路径。type 是文件的类型。

🌐 For every file you add, you must specify the path and type of the file. The path is the relative path to the file from the root of your project. The type is the type of the file.

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

🌐 You can read more about the registry item schema and file types in the registry item schema docs.

构建你的注册表

🌐 Build your registry

安装 shadcn CLI

🌐 Install the shadcn CLI

pnpmnpmyarnbun
pnpm add shadcn@latest
Copy

添加一个构建脚本

🌐 Add a build script

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

🌐 Add a registry:build script to your package.json file.

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

运行构建脚本

🌐 Run the build script

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

🌐 Run the build script to generate the registry JSON files.

pnpmnpmyarnbun
pnpm registry:build
Copy

为你的注册表提供服务

🌐 Serve your registry

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

🌐 If you're running your registry on Next.js, you can now serve your registry by running the next server. The command might differ for other frameworks.

pnpmnpmyarnbun
pnpm dev
Copy

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

🌐 Your files will now be served at http://localhost:3000/r/[NAME].json eg. http://localhost:3000/r/hello-world.json.

发布你的注册表

🌐 Publish your registry

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

🌐 To make your registry available to other developers, you can publish it by deploying your project to a public URL.

指南

🌐 Guidelines

以下是构建注册表组件时要遵循的一些准则。

🌐 Here are some guidelines to follow when building components for a registry.

• 将你的注册表项放在 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 安装

🌐 Install using the CLI

要使用 shadcn CLI 安装注册表项，请使用 add 命令，然后跟上注册表项的 URL。

🌐 To install a registry item using the shadcn CLI, use the add command followed by the URL of the registry item.

pnpmnpmyarnbun
pnpm dlx shadcn@latest add http://localhost:3000/r/hello-world.json
Copy

请参阅 命名空间注册表 文档，了解如何从命名空间注册表安装注册表条目的更多信息。

🌐 See the Namespaced Registries docs for more information on how to install registry items from a namespaced registry.