入门

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

¥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.

registry.json

仅当你使用 shadcn CLI 构建注册表时，才需要 registry.json 文件。

¥The registry.json file is only required if you're using the shadcn CLI to build your registry.

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

¥If you're using a different build system, you can skip this step as long as your build system produces valid JSON files that conform to the registry-item schema specification.

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

添加一个注册表项

¥Add a registry item

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

registry
└── hello-world
    └── hello-world.tsx

// tailwind.config.ts
export default {
  content: ["./registry/**/*.{js,ts,jsx,tsx}"],
}

{
  "$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/hello-world/hello-world.tsx",
          "type": "registry:component"
        }
      ]
    }
  ]
}

构建你的注册表

¥Build your registry

pnpm add shadcn@canary

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

pnpm registry:build

为你的注册表提供服务

¥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.

pnpm dev

你的文件现在将在 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.

• 块定义需要以下属性：name、description、type 和 files。

  ¥The following properties are required for the block definition: name, description, type and files.

• 确保列出 registryDependencies 中的所有注册表依赖。注册表依赖是注册表中组件的名称，例如 input、button、card 等，或注册表项的 URL，例如 http://localhost:3000/r/editor.json。

  ¥Make sure to list all registry dependencies in registryDependencies. A registry dependency is the name of the component in the registry eg. input, button, card, etc or a URL to a registry item eg. http://localhost:3000/r/editor.json.

• 确保列出 dependencies 中的所有依赖。依赖是注册表中包的名称，例如 zod、sonner 等。要设置版本，你可以使用 name@version 格式，例如 zod@^3.20.0。

  ¥Make sure to list all dependencies in dependencies. A dependency is the name of the package in the registry eg. zod, sonner, etc. To set a version, you can use the name@version format eg. zod@^3.20.0.

• 导入应始终使用 @/registry 路径。例如 import { HelloWorld } from "@/registry/hello-world/hello-world"

  ¥Imports should always use the @/registry path. eg. import { HelloWorld } from "@/registry/hello-world/hello-world"

• 理想情况下，将你的文件放在 components、hooks、lib 目录中的注册表项中。

  ¥Ideally, place your files within a registry item in components, hooks, lib directories.

使用 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.

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