registry-item.json

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

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

Copy{
  "$schema": "https://shadcn-vue.com/schema/registry-item.json",
  "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"
    },
    {
      "path": "registry/new-york/HelloWorld/useHelloWorld.ts",
      "type": "registry:hook"
    }
  ]
}

定义

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

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

name

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

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

Copy{
  "name": "hello-world"
}

title

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

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

Copy{
  "title": "Hello World"
}

description

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

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

Copy{
  "description": "A simple hello world component."
}

type

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

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

Copy{
  "type": "registry:block"
}

支持以下类型：

🌐 The following types are supported:

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.

Copy{
  "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.

Copy{
  "dependencies": [
    "reka-ui",
    "zod",
    "lucide-vue-next",
    "name@1.0.2"
  ]
}

registryDependencies

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

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

• 对于 shadcn/ui 注册表项，例如 button、input、select 等，请使用名称，例如 ['button', 'input', 'select']。
• 对于自定义注册表项，使用注册表项的 URL，例如 ['https://example.com/r/hello-world.json']。

Copy{
  "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.

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

Copy{
  "files": [
    {
      "path": "registry/new-york/HelloWorld/page.vue",
      "type": "registry:page",
      "target": "pages/hello/index.vue"
    },
    {
      "path": "registry/new-york/HelloWorld/HelloWorld.vue",
      "type": "registry:component"
    },
    {
      "path": "registry/new-york/HelloWorld/useHelloWorld.ts",
      "type": "registry:hook"
    },
    {
      "path": "registry/new-york/HelloWorld/.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-vue 命令行工具会读取项目的 components.json 文件以确定目标路径。对于某些文件，例如路由或配置，你可以手动指定目标路径。

🌐 By default, the shadcn-vue 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.

Copy{
  "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.

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

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

Copy{
  "css": {
    "@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)"
      }
    }
  }
}

docs

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

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

Copy{
  "docs": "Remember to add the FOO_BAR environment variable to your .env file."
}

categories

使用 categories 来整理你的注册表项。

🌐 Use categories to organize your registry item.

Copy{
  "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.

Copy{
  "meta": { "foo": "bar" }
}