113k
新建

registry-item.json

Previous

注册表 item 的规范。

registry-item.json schema 用于定义你自己的自定义注册表 item。

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"],
  "devDependencies": ["tw-animate-css"],
  "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": "oklch(0.205 0.015 18)"
    },
    "dark": {
      "brand": "oklch(0.205 0.015 18)"
    }
  }
}
查看更多示例

定义

你可以在这里查看 registry-item.json 的 JSON Schema。

$schema

$schema 属性用于指定 registry-item.json 文件所对应的 schema。

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

name

item 的名称。它用于在注册表中标识该 item。对于你的注册表来说，它应该是唯一的。

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

title

你的注册表 item 的可读标题。保持简短且有描述性。

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

description

你的注册表 item 的描述。它可以比 title 更长、更详细。

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

type

type 属性用于指定你的注册表 item 类型。项目解析该 item 时，会根据它来确定 item 的类型和目标路径。

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

支持以下类型：

类型描述
registry:base用于整个设计系统。
registry:block用于包含多个文件的复杂组件。
registry:component用于简单组件。
registry:font用于字体。
registry:lib用于库和工具函数。
registry:hook用于 hooks。
registry:ui用于 UI 组件和单文件原语。
registry:page用于页面或基于文件的路由。
registry:file用于其他杂项文件。
registry:style用于注册表样式，例如 new-york。
registry:theme用于主题。
registry:item用于通用注册表 item。

author

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

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

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

dependencies

dependencies 属性用于指定注册表 item 的依赖。这是给 npm 包用的。

使用 @version 来指定包版本。

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

devDependencies

devDependencies 属性用于指定注册表 item 的开发依赖。这些是只在开发阶段需要的 npm 包。

使用 @version 来指定包版本。

registry-item.json
{
  "devDependencies": ["tw-animate-css", "name@1.2.0"]
}

registryDependencies

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

  • 对于 shadcn/ui 注册表 item，例如 button、input、select 等，直接使用名称，例如 ['button', 'input', 'select']。
  • 对于命名空间注册表 item，例如 @acme，直接使用名称，例如 ['@acme/input-form']。
  • 对于自定义注册表 item，使用注册表 item 的 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 属性用于指定注册表 item 的文件。每个文件都有 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

path 属性用于指定注册表中文件的路径。构建脚本会使用该路径来解析、转换并构建注册表 JSON payload。

type

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 属性为注册表 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

用于为你的注册表 item 定义 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 为你的注册表 item 添加环境变量。

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 文件中。已有变量不会被覆盖。

font

font 属性对 registry:font item 是必需的。它会配置字体族、提供方、导入名、CSS 变量，以及在非 Next.js 项目中需要安装的 npm 包。

registry-item.json
{
  "font": {
    "family": "'Inter Variable', sans-serif",
    "provider": "google",
    "import": "Inter",
    "variable": "--font-sans",
    "subsets": ["latin"],
    "dependency": "@fontsource-variable/inter"
  }
}
属性类型必需描述
familystring是CSS font-family 值。
providerstring是字体提供方。目前只支持 google。
importstring是来自 next/font/google 的字体导入名。
variablestring是字体对应的 CSS 变量名（例如 --font-sans、--font-mono）。
weightstring[]否要包含的字体字重数组。
subsetsstring[]否要包含的字体子集数组。
selectorstring否要应用字体的 CSS 选择器。默认是 html。
dependencystring否非 Next.js 项目需要安装的 npm 包（例如 @fontsource-variable/inter）。

docs

使用 docs 在通过 CLI 安装你的注册表 item 时展示自定义文档或消息。

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

categories

使用 categories 来组织你的注册表 item。

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

meta

使用 meta 为注册表 item 添加额外元数据。你可以添加任何希望对该 item 可用的键值对。

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