shadcn-vue registry-item.json 完整规范：自定义组件注册表条目字段详解与实战指南

UI组件前端【免费下载链接】shadcn-vueVue port of shadcn-ui项目地址https://gitcode.com/gh_mirrors/sh/shadcn-vue点击查看免费下载导读registry-item.json是 shadcn-vue 组件注册表registry生态的核心规范文件用于描述每一个可被 CLI 安装的注册表条目registry item——无论是单个组件、完整的 block、自定义 hook、样式主题还是页面路由。本文基于 registry-item-json 官方文档逐字段拆解其完整 JSON Schema 定义并结合 CLI 源码中的 Zod 校验实现、仓库内置的 JSON Schema 文件 以及 实际构建产物 进行纵深讲解。读完本文你将能够编写出语法正确、可被shadcn-vue add命令正常解析和安装的自定义注册表条目并理解每个字段在 CLI 安装流程中的真实作用。registry-item.json 是什么registry-item.json是描述单个注册表条目的 Schema 规范。它定义了一个条目所需的全部元数据名称、类型、依赖、文件清单、CSS 变量、Tailwind 配置等。该规范用于运行自己的组件注册表配合registry.json见 registry-json 文档定义整个注册表再由shadcn-vue build命令构建出一个个独立的.json文件默认输出到public/r/目录被 CLI 直接消费执行npx shadcn-vuelatest add url或add owner/repo/item时CLI 会拉取对应条目 JSON按规范解析并写入目标项目。一个最小的registry-item.json示例如下来自 官方文档{ $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 } ] }在仓库中可以找到大量真实的构建产物示例例如 button.json其结构包含了$schema、name、dependencies、files每个文件内联content源码和type字段是理解该规范构建后形态的最佳参考。字段定义Definitions完整 JSON Schema 定义可以在仓库的 apps/v4/public/schema/registry-item.json 中查看CLI 侧的运行时校验则使用 Zod 实现位于 packages/cli/src/registry/schema.ts文件头部注释明确要求两处 Schema 保持同步。下面逐字段展开。$schema$schema属性用于指定registry-item.json文件所遵循的 Schema为编辑器提供校验与自动补全支持。{ $schema: https://shadcn-vue.com/schema/registry-item.json }在 Zod 校验中该字段是可选的z.string().optional()但在仓库内的真实产物中普遍存在例如 button.json 的首行即是该声明。namename属性指定注册表条目的名称用于在注册表中唯一标识该条目。JSON Schema 中要求它必须唯一[name] should be unique for your registry且是顶层必填字段之一Schema 的required: [name, type]。{ name: hello-world }从 schema.ts 的registryItemCommonSchema可见name被定义为z.string()属于所有类型条目共享的必填字段。名称还会直接决定构建产物文件的命名按 getting-started 文档 的说明shadcn-vue build会在public/r下生成public/r/name.json。titletitle是注册表条目的人类可读标题要求简短且具有描述性。{ title: Hello World }它在 Schema 中是可选字段z.string().optional()主要用于注册表展示、CLI 安装时的界面提示等场景。descriptiondescription是对注册表条目的描述可以比title更长、更详细。{ description: A simple hello world component. }在 getting-started 文档 的 Guidelines 中明确指出block 定义中name、description、type和files四个属性是必填的虽然 JSON Schema 层面只强制name和type。typetype属性指定注册表条目的类型它决定了 CLI 在项目中的解析与目标路径处理方式JSON Schema 描述为The type of the item. This is used to determine the type and target path of the item when resolved for a project.。{ type: registry:block }官方文档列出的支持类型如下TypeDescriptionregistry:blockUse for complex components with multiple files.registry:componentUse for simple components.registry:libUse for lib and utils.registry:hookUse for composables (hooks).registry:uiUse for UI components and single-file primitivesregistry:pageUse for page or file-based routes.registry:fileUse for miscellaneous files.在 CLI 源码 schema.ts 中类型枚举更完整额外包含registry:composable、registry:theme、registry:style、registry:item、registry:base、registry:font以及仅内部使用的registry:example和registry:internal。仓库的 JSON Schemaregistry-item.json中同样列出了registry:theme、registry:style、registry:base、registry:font等扩展类型。这些类型在 examples 文档 中有大量实战案例registry:style用于定义完整样式方案可通过extends继承 shadcn-vue 或设为extends: none从零开始registry:theme用于定义主题可整体覆盖background、foreground、primary、ring、sidebar-primary等 CSS 变量registry:block用于安装复杂页面块例如从 shadcn-vue 注册表安装Login01block 并覆盖其底层原语组件registry:component用于简单组件也可携带自定义 CSS 规则。authorauthor属性用于指定注册表条目的作者。它可以与整个注册表的作者相同也可以为该条目单独设置。{ author: John Doe johndoe.com }JSON Schema 推荐格式为username urlZod 校验要求最少 2 个字符z.string().min(2).optional()。dependenciesdependencies属性用于指定注册表条目所需的npm 包依赖。使用version语法可以锁定版本。{ dependencies: [ reka-ui, zod, lucide/vue, name1.0.2 ] }CLI 安装时会将这些依赖写入目标项目并交由包管理器安装。注意 getting-started 文档 的说明依赖项是注册表中的包名如zod、sonner如需指定版本使用nameversion格式如zod^3.20.0。Schema 中还提供了对应的devDependencies数组用于开发依赖。registryDependenciesregistryDependencies用于声明注册表级依赖可以是名称或 URL对于 shadcn/ui 注册表条目如button、input、select直接使用名称例如[button, input, select]对于自定义注册表条目使用该条目的 URL例如[https://example.com/r/hello-world.json]。{ registryDependencies: [ button, input, select, https://example.com/r/editor.json ] }官方文档特别注明CLI 会自动解析远程注册表依赖The CLI will automatically resolve remote registry dependencies.即依赖项可以跨注册表递归拉取。构建后的真实示例可见 button.json 中的dependencies: [reka-ui]以及各组件产物间通过registryDependencies形成的依赖网络。filesfiles属性用于指定注册表条目所包含的文件清单。每个文件对象包含path、type和可选的target属性。target属性对于registry:page和registry:file类型是必填的。这一点在 JSON Schema 中有强制约束registry-item.json当type为registry:file或registry:page时path、type、target三者缺一不可其他类型则只需path和type。Zod 侧同样使用 discriminated union 实现了这一约束schema.ts。{ 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 } ] }pathpath属性指定文件在注册表中的路径。该路径会被构建脚本用于解析、转换并构建出注册表 JSON 载荷文档原文This path is used by the build script to parse, transform and build the registry JSON payload.。构建产物中源文件内容会被内联进content字段——见 button.json 中每个文件对象的content属性。typetype属性指定文件的类型取值见上文 type 小节。targettarget属性用于指示文件在目标项目中的放置位置。它是可选的且仅对registry:page和registry:file类型必填。默认情况下shadcn-vueCLI 会读取项目的components.json文件来决定目标路径对于路由、配置文件等无法由 components.json 推断位置的场景需要手动指定target。使用~表示项目根目录例如~/foo.config.js对应target: ~/.env表示写入项目根目录下的.env。在 getting-started 文档 的安全说明中亦提到CLI 会拒绝path和target中绝对路径或以..逃逸项目目录的值这是对误配置和恶意条目的防御但并非沙箱。tailwind已废弃DEPRECATEDTailwind v4 项目请改用cssVars.theme。tailwind属性用于 Tailwind 配置如theme、plugins和content。其中tailwind.config属性可以向条目添加颜色、动画和插件。{ 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 } } } } } }Schema 中tailwind.config支持content字符串数组、theme任意对象和plugins字符串数组三个子字段registry-item.json。FAQ 文档 中给出了向 Tailwind 添加自定义颜色的完整套路先在cssVars中定义色值变量再在tailwind.config.theme.extend.colors中映射为hsl(var(--brand-background))形式CLI 会同步更新项目 CSS 文件与tailwind.config.js之后即可直接使用bg-brand、text-brand-accent等工具类。cssVarscssVars用于为注册表条目定义 CSS 变量支持light与dark两套主题取值{ cssVars: { light: { brand: 20 14.3% 4.1%, radius: 0.5rem }, dark: { brand: 20 14.3% 4.1% } } }Schema 中该字段还支持theme子对象CSS variables for the theme directive. For Tailwind v4 projects only.用于 Tailwind v4 的theme指令registry-item.json。Zod 定义见 schema.ts包含theme、light、dark三个可选记录。按 examples 文档cssVars.theme还可定义字体变量如font-sans: Inter, sans-serif、阴影shadow-card: 0 0 0 1px rgba(0, 0, 0, 0.1)乃至覆盖 Tailwind 的间距与断点变量。css使用css属性可以向项目的 CSS 文件添加新规则例如layer base、layer components、utility、keyframes等。{ 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) } } } }Schema 中的cssValue定义registry-item.json允许递归嵌套值可以是字符串CSS 属性值或直接 CSS 字符串也可以是嵌套对象子属性、选择器或 at-rule空对象允许用于无内容的 at-rule。Zod 侧对应registryItemCssSchema z.record(z.string(), cssValueSchema)schema.ts同样支持字符串、数组和递归记录。在 examples 文档 中还有大量进阶用法基础样式layer base中为h1/h2设置字号、组件样式为card类设置圆角、内边距、阴影、简单工具类utility content-auto、复杂工具类嵌套::-webkit-scrollbar伪元素、以及函数式工具类utility tab-*。docs使用docs属性可以在通过 CLI 安装注册表条目时显示自定义文档或提示消息。{ docs: Remember to add the FOO_BAR environment variable to your .env file. }Schema 将其描述为一段 Markdown 字符串The documentation for the registry item. This is a markdown string.。这是向安装者传达环境变量、手动配置步骤等安装后须知的常用手段。categories使用categories属性来组织注册表条目。{ categories: [sidebar, dashboard] }meta使用meta属性为注册表条目添加附加元数据可以是任意键值对供注册表条目后续使用。{ meta: { foo: bar } }Schema 中meta为additionalProperties: true的开放对象Zod 定义为z.record(z.string(), z.any())schema.ts。源码级补充Schema 中的其他字段与约束除了上述文档字段仓库内的 JSON Schema 与 Zod 实现 还定义了以下值得了解的扩展字段envVarsRecordstring, string条目所需的环境变量键值对CLI 会将其写入项目的.env文件Schema 描述Key-value pairs that will be added to the projects .env file.extendsregistry:style专用声明继承的样式设为none表示从零开始。这一用法在 examples 文档 的 Custom style from scratch 案例中有完整演示style、iconLibrary、baseColor、themeregistry:base专用字段用于定义基础配置Schema 通过allOf条件约束这些字段仅允许出现在registry:base条目中registry-item.jsonfontregistry:font专用字段必填family、provider当前仅google、import、variable可选weight、subsets、selector、dependency同样通过allOf约束其他类型不得携带fontregistry-item.jsonconfigregistry:base条目可携带的深度可选原始配置对象rawConfigSchema.deepPartial()。顶层必填字段仅为name与typeregistry-item.json其余字段按需使用。端到端实战从编写到安装将registry-item.json规范落地到真实项目中的完整链路如下详细步骤见 getting-started 文档编写条目在registry/[STYLE]/[NAME]目录下放置组件源码例如registry/new-york/HelloWorld/HelloWorld.vue并在registry.json的items数组中按本规范描述该条目若使用自定义目录记得将其加入tailwind.config.ts的content配置构建安装 CLI 并执行npm run registry:build即shadcn-vue build默认在public/r下生成public/r/name.json格式的独立条目文件可用--output改变输出目录部署将项目部署到公网用户即可通过npx shadcn-vuelatest add http://localhost:3000/r/hello-world.json或 GitHub 形式npx shadcn-vuelatest add owner/repo/hello-world安装条目鉴权可选CLI 不内置注册表鉴权官方建议在注册表服务端处理常见做法是使用token查询参数如?token[SECURE_TOKEN_HERE]对无效 token 返回 401CLI 与 Open in v0 都会处理 401 并向用户展示提示。复杂条目参考FAQ 文档 给出了一个复杂组件的完整示例——一个同时安装页面、两个组件、一个 composable、一个日期格式化工具函数和配置文件的 block{ $schema: https://shadcn-vue.com/schema/registry-item.json, name: hello-world, title: Hello World, type: registry:block, description: A complex hello world component, files: [ { path: registry/new-york/HelloWorld/page.vue, type: registry:page, target: pages/hello/index.vue }, { path: registry/new-york/HelloWorld/components/HelloWorld.vue, type: registry:component }, { path: registry/new-york/HelloWorld/components/FormattedMessage.vue, type: registry:component }, { path: registry/new-york/HelloWorld/composables/useHello.ts, type: registry:hook }, { path: registry/new-york/HelloWorld/lib/formatDate.ts, type: registry:utils }, { path: registry/new-york/HelloWorld/hello.config.ts, type: registry:file, target: ~/hello.config.ts } ] }这个例子清晰展示了files数组如何把不同类型的源文件页面、组件、hook、工具函数、配置文件组织进同一个条目以及target如何精确控制registry:page与registry:file的落盘位置。小结registry-item.json是 shadcn-vue 注册表体系的最小交付单元。掌握name、type、files含path/type/target三个核心字段即可发布第一个可安装的组件而dependencies、registryDependencies、cssVars、css、tailwind等字段则让条目可以携带完整的依赖树、主题变量与样式规则实现一条命令装好一个可运行的页面块。实际编写时可对照仓库中的 JSON Schema 校验字段合法性参考 CLI 的 Zod 实现 理解运行时约束尤其是registry:page/registry:file必填target、registry:font必填font、registry:base专用字段限制等并以 构建产物 为范本即可快速构建出健壮、可移植的自定义组件注册表。赞分享UI组件前端【免费下载链接】shadcn-vueVue port of shadcn-ui项目地址https://gitcode.com/gh_mirrors/sh/shadcn-vue点击查看免费下载相关推荐shadcn-svelte 自定义组件注册表核心规范registry-item.json 完整字段详解与 CLI 实战shadcn svelte 自定义组件注册表核心规范registry item.json 完整字段详解与 CLI 实战 导读 registry item.jsUI组件前端CLI开发工具终极指南如何快速上手Deforum扩展并创建惊艳AI动画终极指南如何快速上手Deforum扩展并创建惊艳AI动画 Stable Diffusion Deforum扩展是AUTOMATIC1111 WebUI中最强大UI组件前端MCP registry 的 server.json 格式规范详解从字段定义到注册表校验实现的完整指南MCP registry 的 server.json 格式规范详解从字段定义到注册表校验实现的完整指南 server.json 是 MCP registry后端AI Agent工具调用上一篇抖音批量下载工具教程从单个视频到整站存档的完整上手指南下一篇scan4all 中的 XPath 网页数据提取深入解析 htmlquery 查询库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考