入门指南

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

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

registry.json

如果您使用 shadcn-vue CLI 来构建注册表，则必须提供 registry.json 文件。

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

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

添加注册表项

Copy<script setup lang="ts">
import { Button } from "@/components/ui/button"
</script>

<template>
  <Button>Hello World</Button>
</template>

Copyregistry
└── new-york
    └── HelloWorld
        └── HelloWorld.vue

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

Copy{
  "$schema": "https://vue.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/HelloWorld/HelloWorld.vue",
          "type": "registry:component"
        }
      ]
    }
  ]
}

构建您的注册表

pnpmnpmyarnbun
pnpm add shadcn-vue@latest
Copy

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

pnpmnpmyarnbun
pnpm registry:build
Copy

托管您的注册表

如果您在 Nuxt 上运行注册表，现在可以通过运行 nuxt 服务器来托管它。其他框架的命令可能有所不同。

pnpmnpmyarnbun
pnpm dev
Copy

您的文件现在将托管在 https://:3000/r/[NAME].json，例如 https://:3000/r/hello-world.json。

发布您的注册表

为了让其他开发者能够使用您的注册表，您可以将项目部署到公共 URL 来发布它。

添加身份验证

shadcn-vue CLI 没有提供内置的注册表身份验证方式。我们建议在您的注册表服务器端处理授权。

一种常见的简单方法是使用 token 查询参数来验证对注册表的请求。例如 https://: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://: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-vue CLI 安装注册表项，请使用 add 命令，后跟注册表项的 URL。

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