99.1k

registry-item.json

上一页

注册表条目规范。

registry-item.json Schema 用于定义自定义注册表条目。

registry-item.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "hello-world",
  "type": "registry:block",
  "title": "Hello World",
  "description": "A simple hello world component.",
  "registryDependencies": [
    "button",
    "@acme/input-form",
    "https://example.com/r/foo"
  ],
  "dependencies": ["is-even@3.0.0", "motion"],
  "files": [
    {
      "path": "registry/new-york/hello-world/hello-world.tsx",
      "type": "registry:component"
    },
    {
      "path": "registry/new-york/hello-world/use-hello-world.ts",
      "type": "registry:hook"
    }
  ],
  "cssVars": {
    "theme": {
      "font-heading": "Poppins, sans-serif"
    },
    "light": {
      "brand": "20 14.3% 4.1%"
    },
    "dark": {
      "brand": "20 14.3% 4.1%"
    }
  }
}
查看更多示例

字段说明

registry-item.json 的完整 JSON Schema 可在此处查看。

$schema

$schema 字段用于声明 registry-item.json 使用的 Schema。

registry-item.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json"
}

name

条目名称，用于注册表中的唯一标识。

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

title

显示给用户的标题，建议简洁明了。

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

description

条目描述，可比标题更详细。

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

type

type 用于指定条目类型，解析到项目时会据此确定目标路径。

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

支持以下类型：

Type说明
registry:block适用于包含多文件的复杂组件。
registry:component适用于简单组件。
registry:lib适用于库和工具函数。
registry:hook适用于 Hooks。
registry:ui适用于 UI 组件或单文件原子组件。
registry:page适用于页面或基于文件的路由。
registry:file适用于其他类型的文件。
registry:style适用于样式条目，例如 new-york。
registry:theme适用于主题。
registry:item适用于通用注册表条目。

author

author 字段用于标注条目的作者信息。

可以是条目作者，也可以与注册表作者一致。

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

dependencies

dependencies 用于声明条目所需的 npm 包依赖。

可通过 @version 指定依赖版本。

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

registryDependencies

用于声明注册表依赖，可以是名称、命名空间或 URL。

  • 对于 shadcn/ui 的条目（如 button、input、select），直接写名称：['button', 'input', 'select']
  • 对于命名空间条目（如 @acme），写完整名称：['@acme/input-form']
  • 自定义注册表条目使用完整 URL：['https://example.com/r/hello-world.json']
registry-item.json
{
  "registryDependencies": [
    "button",
    "@acme/input-form",
    "https://example.com/r/editor.json"
  ]
}

提示：CLI 会自动解析远程注册表依赖。

files

files 描述条目包含的文件。每个文件需指定 path、type，可选的 target 表示目标路径。

registry:page 与 registry:file 类型必须提供 target。

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

path

文件在注册表中的路径。构建脚本会根据该路径解析并生成 JSON。

type

文件类型，详见 type 段落。

target

target 指明文件在项目中的放置位置，仅 registry:page 与 registry:file 必填。

默认情况下，shadcn CLI 会读取项目根目录的 components.json 来推断目标路径。对于路由、配置等文件，可以手动指定。

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

tailwind

已废弃： 在 Tailwind v4 项目中请改用 cssVars.theme。

tailwind 字段用于配置 Tailwind，例如 theme、plugins、content 等。

可通过 tailwind.config 添加颜色、动画、插件等内容。

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 变量。

registry-item.json
{
  "cssVars": {
    "theme": {
      "font-heading": "Poppins, sans-serif"
    },
    "light": {
      "brand": "20 14.3% 4.1%",
      "radius": "0.5rem"
    },
    "dark": {
      "brand": "20 14.3% 4.1%"
    }
  }
}

css

通过 css 可向项目 CSS 文件新增规则，例如 @layer base、@layer components、@utility、@keyframes、@plugin 等。

registry-item.json
{
  "css": {
    "@plugin @tailwindcss/typography": {},
    "@plugin foo": {},
    "@layer base": {
      "body": {
        "font-size": "var(--text-base)",
        "line-height": "1.5"
      }
    },
    "@layer components": {
      "button": {
        "background-color": "var(--color-primary)",
        "color": "var(--color-white)"
      }
    },
    "@utility text-magic": {
      "font-size": "var(--text-base)",
      "line-height": "1.5"
    },
    "@keyframes wiggle": {
      "0%, 100%": {
        "transform": "rotate(-3deg)"
      },
      "50%": {
        "transform": "rotate(3deg)"
      }
    }
  }
}

envVars

通过 envVars 向条目添加环境变量。

registry-item.json
{
  "envVars": {
    "NEXT_PUBLIC_APP_URL": "http://localhost:4000",
    "DATABASE_URL": "postgresql://postgres:postgres@localhost:5432/postgres",
    "OPENAI_API_KEY": ""
  }
}

环境变量会写入 .env.local 或 .env 文件，已有变量不会被覆盖。

docs

通过 docs 在 CLI 安装过程中展示自定义文档或提示信息。

registry-item.json
{
  "docs": "To get an OPENAI_API_KEY, sign up for an account at https://platform.openai.com."
}

categories

使用 categories 为条目归类。

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

meta

meta 可添加额外元数据，自由携带任意键值对。

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