🌐 Nodejs.cn
新建

registry-item.json

Previous

注册表项的规范。

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.",
  "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)"
    }
  }
}
查看更多示例

定义

🌐 Definitions

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

🌐 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

条目的名称。用于在注册表中识别该条目。对于你的注册表，它应该是唯一的。

🌐 The name of the item. This is used to identify the item in the registry. It should be unique for your registry.

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. This is used to determine the type and target path of the item when resolved for a project.

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

支持以下类型：

🌐 The following types are supported:

类型描述
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 属性用于指定注册表项的作者。

🌐 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"
  ]
}

devDependencies

devDependencies 属性用于指定你的注册项的开发依赖。这些是仅在开发过程中需要的 npm 包。

🌐 The devDependencies property is used to specify the dev dependencies of your registry item. These are npm packages that are only needed during development.

使用 @version 指定软件包的版本。

🌐 Use @version to specify the version of the package.

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

registryDependencies

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

🌐 Used for registry dependencies. Can be names, namespaced or URLs.

  • 对于 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 将自动解决远程注册表依赖。

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

target 属性是 registry:page 和 registry:file 类型所必需的。

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 数据。

🌐 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 命令行工具会读取项目的 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 v4 项目中请改用 cssVars.theme。

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": {
    "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 等。

🌐 Use css to add new rules to the project's CSS file eg. @layer base, @layer components, @utility, @keyframes, @plugin, etc.

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 将环境变量添加到你的注册表项中。

🌐 Use envVars to add environment variables to your registry 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 文件中。现有的变量不会被覆盖。

🌐 Environment variables are added to the .env.local or .env file. Existing variables are not overwritten.

docs

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

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

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

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" }
}