Docs
registry-item.json

registry-item.json

注册表项的规范。

registry-item.json 架构用于定义自定义注册表项。

¥The registry-item.json schema is used to define your custom registry items.

registry-item.json
{
  "$schema": "https://shadcn.nodejs.cn/schema/registry-item.json",
  "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"
    },
    {
      "path": "registry/hello-world/use-hello-world.ts",
      "type": "registry:hook"
    }
  ]
}

定义

¥Definitions

你可以查看 registry-item.json 此处 的 JSON 模式。

¥You can see the JSON Schema for registry-item.json here.

$schema

$schema 属性用于指定 registry-item.json 文件的架构。

¥The $schema property is used to specify the schema for the registry-item.json file.

registry-item.json
{
  "$schema": "https://shadcn.nodejs.cn/schema/registry-item.json"
}

name

name 属性用于指定注册表项的名称。

¥The name property is used to specify the name of your registry item.

registry-item.json
{
  "name": "hello-world"
}

title

注册表项的人性化标题。保持简短和描述性。

¥A human-readable title for your registry item. Keep it short and descriptive.

registry-item.json
{
  "title": "Hello World"
}

description

注册表项的描述。这可能比 title 更长更详细。

¥A description of your registry item. This can be longer and more detailed than the title.

registry-item.json
{
  "description": "A simple hello world component."
}

type

type 属性用于指定注册表项的类型。

¥The type property is used to specify the type of your registry item.

registry-item.json
{
  "type": "registry:block"
}

支持以下类型：

¥The following types are supported:

类型描述
registry:block用于具有多个文件的复杂组件。
registry:component用于简单组件。
registry:lib用于 lib 和 utils。
registry:hook用于钩子。
registry:ui用于 UI 组件和单文件原语
registry:page用于页面或基于文件的路由。
registry:file用于杂项文件。

author

author 属性用于指定注册表项的作者。

¥The author property is used to specify the author of the registry item.

它可以是注册表项独有的，也可以与注册表的作者相同。

¥It can be unique to the registry item or the same as the author of the registry.

registry-item.json
{
  "author": "John Doe <john@doe.com>"
}

dependencies

dependencies 属性用于指定注册表项的依赖。这适用于 npm 包。

¥The dependencies property is used to specify the dependencies of your registry item. This is for npm packages.

使用 @version 指定注册表项的版本。

¥Use @version to specify the version of your registry item.

registry-item.json
{
  "dependencies": [
    "@radix-ui/react-accordion",
    "zod",
    "lucide-react",
    "name@1.0.2"
  ]
}

registryDependencies

用于注册表依赖。可以是名称或 URL。

¥Used for registry dependencies. Can be names or URLs.

  • 对于 shadcn/ui 注册表项（例如 button、input、select 等），请使用名称，例如 ['button', 'input', 'select']。

    ¥For shadcn/ui registry items such as button, input, select, etc use the name eg. ['button', 'input', 'select'].

  • 对于自定义注册表项，请使用注册表项的 URL，例如 ['https://example.com/r/hello-world.json']。

    ¥For custom registry items use the URL of the registry item eg. ['https://example.com/r/hello-world.json'].

registry-item.json
{
  "registryDependencies": [
    "button",
    "input",
    "select",
    "https://example.com/r/editor.json"
  ]
}

注意：CLI 将自动解析远程注册表依赖。

¥Note: The CLI will automatically resolve remote registry dependencies.

files

files 属性用于指定注册表项的文件。每个文件都有一个 path、type 和 target（可选）属性。

¥The files property is used to specify the files of your registry item. Each file has a path, type and target (optional) property.

registry:page 和 registry:file 类型需要 target 属性。

¥The target property is required for registry:page and registry:file types.

registry-item.json
{
  "files": [
    {
      "path": "registry/hello-world/page.tsx",
      "type": "registry:page",
      "target": "app/hello/page.tsx"
    },
    {
      "path": "registry/hello-world/hello-world.tsx",
      "type": "registry:component"
    },
    {
      "path": "registry/hello-world/use-hello-world.ts",
      "type": "registry:hook"
    },
    {
      "path": "registry/hello-world/.env",
      "type": "registry:file",
      "target": "~/.env"
    }
  ]
}

path

path 属性用于指定注册表中文件的路径。此路径由构建脚本用于解析、转换和构建注册表 JSON 负载。

¥The path property is used to specify the path to the file in your registry. This path is used by the build script to parse, transform and build the registry JSON payload.

type

type 属性用于指定文件的类型。有关更多信息，请参阅 type 部分。

¥The type property is used to specify the type of the file. See the type section for more information.

target

target 属性用于指示文件在项目中的位置。这是可选的，仅对 registry:page 和 registry:file 类型是必需的。

¥The target property is used to indicate where the file should be placed in a project. This is optional and only required for registry:page and registry:file types.

默认情况下，shadcn cli 将读取项目的 components.json 文件以确定目标路径。对于某些文件，例如路由或配置，你可以手动指定目标路径。

¥By default, the shadcn cli will read a project's components.json file to determine the target path. For some files, such as routes or config you can specify the target path manually.

使用 ~ 引用项目的根目录，例如 ~/foo.config.js。

¥Use ~ to refer to the root of the project e.g ~/foo.config.js.

tailwind

tailwind 属性用于 tailwind 配置，例如 theme、plugins 和 content。

¥The tailwind property is used for tailwind configuration such as theme, plugins and content.

你可以使用 tailwind.config 属性向注册表项添加颜色、动画和插件。

¥You can use the tailwind.config property to add colors, animations and plugins to your registry item.

registry-item.json
{
  "tailwind": {
    "config": {
      "theme": {
        "extend": {
          "colors": {
            "brand": "hsl(var(--brand))"
          },
          "keyframes": {
            "wiggle": {
              "0%, 100%": { "transform": "rotate(-3deg)" },
              "50%": { "transform": "rotate(3deg)" }
            }
          },
          "animation": {
            "wiggle": "wiggle 1s ease-in-out infinite"
          }
        }
      }
    }
  }
}

cssVars

用于为你的注册表项定义 CSS 变量。

¥Use to define CSS variables for your registry item.

registry-item.json
{
  "cssVars": {
    "light": {
      "brand": "20 14.3% 4.1%",
      "radius": "0.5rem"
    },
    "dark": {
      "brand": "20 14.3% 4.1%"
    }
  }
}

docs

通过 CLI 安装注册表项时，使用 docs 显示自定义文档或消息。

¥Use docs to show custom documentation or message when installing your registry item via the CLI.

registry-item.json
{
  "docs": "Remember to add the FOO_BAR environment variable to your .env file."
}

categories

使用 categories 组织你的注册表项。

¥Use categories to organize your registry item.

registry-item.json
{
  "categories": ["sidebar", "dashboard"]
}

meta

使用 meta 向你的注册表项添加其他元数据。你可以添加任何你希望可用于注册表项的键/值对。

¥Use meta to add additional metadata to your registry item. You can add any key/value pair that you want to be available to the registry item.

registry-item.json
{
  "meta": { "foo": "bar" }
}
registry.json