Coolify 中的 shadcn Registry 实战源码级注册表的编写、依赖寻址与 GitHub 分发【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify本文以 Coolify 仓库中为 AI Agent 编写的技能参考文档 registry.md 为核心完整讲解 shadcn 注册表Registry的编写规范从根registry.json的元数据规则、include模块化拆分、条目字段与依赖寻址方案到 GitHub 仓库作为注册表的消费流程与shadcn build构建验证命令。读完本文你可以独立编写、构建并验证一个可被 CLI 直接安装的 shadcn 源码注册表并理解 CLI 如何解析各类地址裸名、命名空间、URL、文件、GitHub 仓库。一、背景为什么 Coolify 仓库里有这份注册表参考Coolify 是一个开源、可自托管的 PaaSVercel/Heroku/Netlify 的替代方案其 Web 前端历史上经历过一次 V5 重构该版本采用 React、Inertia、shadcn 与 TypeScript 技术栈。根据 docs/v5/package.md 的归档记录V5 实现被归档后shadcn^4.11.0、React、Inertia 等依赖已从当前package.json移除components.json等前端配置被移入docs/v5/archive/可对照 归档的 components.json。尽管活跃版本已不使用 shadcn仓库仍在.agents/skills/shadcn/目录下保留了一整套面向 AI 编码代理的 shadcn 技能文档用于在需要 shadcn 的上下文中为 Agent 注入项目规范。这套技能由 SKILL.md工作流与关键规则、cli.mdCLI 命令参考、registry.md注册表编写参考以及 rules/ 下的分场景规则文件组成。本文聚焦其中的 registry.md当你想创建、修复、发布或理解一个 shadcn 注册表时它给出的是一套完整的作者指南Authoring Guide。二、心智模型源码注册表 vs 构建产物registry.md 开篇即给出注册表的核心心智模型——一个注册表有两种形态源码注册表Source registry在项目或仓库中手工编写的registry.json。它可以使用include指向其他注册表文件文件路径指向真实源码文件。构建后注册表Built registry生成给 CLI 消费端的 JSON 文件集合通常放在public/r目录下。通过npx shadcnlatest build从源码注册表生成。CLI 安装器消费的是注册表条目的载荷payload。源码注册表只是用真实文件来编写这些载荷的方式——这解释了为什么你不需要手写每个条目的 JSON 内容而只需声明文件路径。另一个关键认知注册表条目不限于 React 组件。它可以分发组件、hooks、工具函数、设计 token、页面、配置文件、文档、规则文件、工作流、模板、MCP 文件等任意项目文件。这决定了后文中registry:*类型体系的宽泛程度。三、根 registry.json 的元数据与规则根注册表文件应定义注册表元数据并提供items或include之一。registry.md 给出的完整示例如下{ $schema: https://ui.shadcn.com/schema/registry.json, name: acme, homepage: https://acme.com, items: [ { name: absolute-url, type: registry:lib, title: Absolute URL, description: A utility to turn any path into an absolute URL., files: [ { path: lib/absolute-url.ts, type: registry:lib } ] } ] }根注册表的硬性规则规则说明必须包含name和homepage二者是根registry.json的必填项items是条目定义数组每个元素是一个可安装的注册表条目include用于拆分可将大注册表拆分为多个文件被包含文件可省略元数据被include的注册表文件不需要name和homepage示例中的registry:lib条目展示了最简形态一个条目名absolute-url即安装时的名字而非文件路径、一个类型registry:lib、展示用的title/description以及一个指向源文件lib/absolute-url.ts的files声明。四、include把大注册表拆成模块当条目数量膨胀时用include保持模块化{ $schema: https://ui.shadcn.com/schema/registry.json, name: acme, homepage: https://acme.com, include: [registry/ui/registry.json, registry/blocks/registry.json] }include的规则集合这部分是排查构建报错的重点路径基准include路径相对于声明它的那个registry.json显式指向include路径必须显式指向一个registry.json文件不能指向目录禁止项不得使用远程 URL、绝对路径或父目录穿越..条目文件路径的基准条目files中的路径相对于声明该条目的注册表文件而不是根注册表重名即失败跨整个解析后的注册表重复的条目名会导致失败。registry.md 用一个具体例子说明相对路径的解析方式若一个被包含文件位于registry/ui/registry.json{ items: [ { name: button, type: registry:ui, files: [ { path: button.tsx, type: registry:ui } ] } ] }则其中的button.tsx会从registry/ui/button.tsx读取而构建后输出的条目路径是相对于根注册表的。也就是说读取时以声明文件为基准输出时以根为基准这个双向基准是理解构建产物的关键。五、条目定义字段全解registry.md 给出一个功能较完整的条目示例一个registry:block类型的登录表单覆盖了大部分常用字段{ name: login-form, type: registry:block, title: Login Form, description: A login form with email and password fields., dependencies: [zod], registryDependencies: [button, input, label], files: [ { path: blocks/login-form.tsx, type: registry:block } ], cssVars: { light: { brand: oklch(0.62 0.18 250) }, dark: { brand: oklch(0.72 0.16 250) } } }重要字段说明name可安装的条目名。它不一定是文件路径——安装时用户通过这个名字引用条目type注册表条目类型取值如registry:ui、registry:block、registry:lib、registry:hook、registry:file、registry:page、registry:theme、registry:style、registry:font、registry:itemfiles由该条目复制或生成的源文件列表dependenciesnpm 运行时依赖本例中的zod会在安装时被写入项目的 npm 依赖devDependenciesnpm 开发依赖registryDependencies本条目所依赖的其他注册表条目下一节详述cssVars、css、tailwind、envVars、docs可选的安装期附加内容例如本例中按light/dark双主题注入的brandCSS 变量。文件files层面的规则文件路径相对于声明它的registry.json与include的路径基准一致registry:file与registry:page类型的文件必须提供target——因为这两类条目的意义就是把文件放到项目中的指定位置源码注册表的文件路径中禁止使用远程文件 URL保持源文件可直接复制粘贴不允许隐式的、仅应用内部可用的导入hidden app-only imports否则安装到其他项目后会直接编译失败。六、registryDependencies条目地址而非文件路径registryDependencies中最容易踩坑的一点其条目是条目地址item address不是文件路径。registry.md 示例{ name: login-form, type: registry:block, registryDependencies: [button, acme/input, acme/ui/card#v1.2.0], files: [ { path: blocks/login-form.tsx, type: registry:block } ] }依赖书写规则裸名如button表示官方 shadcn 条目裸名永远不表示本注册表或本仓库内的条目——要依赖自己注册表里的条目必须使用带命名空间的地址命名空间依赖用namespace/item-name如acme/inputGitHub 依赖用owner/repo/item-name如acme/ui/card需要时用#ref钉住版本如acme/ui/card#v1.2.0ref 不会继承如果owner/repo/foo#v2依赖同仓库v2下的bar必须显式写owner/repo/bar#v2禁止相对依赖如./bar。这套规则与下一节的地址方案address schemes是一套体系的两个视角registryDependencies里写的就是地址字符串。七、地址方案先分类再解析当你面对一个注册表条目字符串时registry.md 要求先分类并给出完整的判别表地址方案Scheme含义buttonshadcn官方 shadcn 条目buttonacme/buttonnamespace已配置注册表acme中的条目buttonacme/ui/buttonnamespace已配置注册表acme中的条目ui/buttonhttps://example.com/r/button.jsonurl该 URL 处的构建后条目 JSON./button.jsonfile磁盘上的构建后条目 JSONacme/ui/buttongithubGitHub 仓库acme/ui中的条目buttonacme/ui/forms/login#maingithubGitHub 仓库acme/ui中mainref 下的条目forms/login两个边界规则值得特别注意带斜杠的条目名是合法的在 namespace 与 GitHub 地址中ui/button、forms/login这类带斜杠的串是条目名不是文件路径.json后缀优先判定为文件地址即使形似 GitHub 仓库路径acme/ui/data/schema.json也会被当作文件路径处理而不是 GitHub 条目地址。对照仓库内 CLI 参考 cli.md 的add命令说明add接受的正是这五种输入形态组件名、带注册表前缀的名字magicui/shimmer-button、GitHub 条目地址owner/repo/item、URL 或本地路径——地址方案表就是这些输入在解析层的分类依据。八、GitHub 仓库即注册表registry.md 定义了一条便捷通道任何带根registry.json的公开 GitHub 仓库都可以充当源码注册表地址格式为owner/repo/item-name[#ref]解析规则路径的前两段是 GitHub owner 与 repo其余所有段都是注册表条目名这再次印证条目名可以带斜杠源码入口永远是根registry.jsonGitHub 注册表是直接被 CLI 消费的源码注册表无需执行shadcn build也无需生成条目 JSON 文件include遵循与本地注册表相同的源码规则当前仅支持github.com的公开仓库私有仓库与 GitHub Enterprise 需要显式的产品决策默认不支持。ref 解析的正确姿势文档在实现层面给出了一条强约束在读取源码文件之前必须先把 ref 解析为 commit SHA。不能直接从raw.githubusercontent.com读取分支这类会移动的 ref因为分支型 ref 可能被缓存数分钟导致同一次命令读到不一致的快照。推荐的解析流程owner/repo[#ref] - resolve ref with git ls-remote - commit SHA - read https://raw.githubusercontent.com/{owner}/{repo}/{sha}/registry.json - read includes and item files from the same SHA这样做的效果是把整条命令锁定在同一个仓库快照上根registry.json、所有include文件、所有条目源文件都来自同一个 commit SHA。补充说明完整的 40 位 commit SHA 本身是稳定的可以直接使用分支、tag 与短 ref 则必须先借助 Git如git ls-remote解析为 commit SHA。九、构建与验证完整命令清单构建源码注册表npx shadcnlatest build npx shadcnlatest build registry.json --output public/r对照 cli.md 中build命令的参数表默认输入为./registry.json默认输出目录为./public/r--output path/-o可指定输出目录--cwd cwd/-c指定工作目录。第一条命令即使用全部默认值第二条命令显式指定输入与输出。检查构建结果命名空间/本地注册表npx shadcnlatest list acme npx shadcnlatest search acme -q login npx shadcnlatest view acme/login-form npx shadcnlatest add acme/login-form --dry-run npx shadcnlatest registry validate ./registry.json直接检查 GitHub 注册表npx shadcnlatest list owner/repo npx shadcnlatest search owner/repo -q login npx shadcnlatest view owner/repo/item npx shadcnlatest add owner/repo/item --dry-run npx shadcnlatest registry validate owner/repo五组命令构成一条渐进的验证链路list/search验证条目能否被发现view验证元数据与文件内容是否正确add --dry-run验证在真实项目中落盘的路径与变更--dry-run不写入任何文件registry validate对源码注册表本身做结构校验。按 cli.md 的search说明list是search的别名不带-q时列出全部条目可用-t按类型过滤如ui、block、hook--limit/--offset分页默认上限 100 条。十、面向 CLI 实现者的工程约束registry.md 最后一段是写给在 shadcn/ui 代码库中实现注册表逻辑的开发者的一组约束从源码结构看这是一份架构守则而非业务规则地址解析保持纯函数化、可测试Keep address parsing pure and testable校验器禁止副作用Do not add side effects to validators保留既有行为官方 shadcn、namespace、URL、file 四种方案的解析行为不得被新方案如 GitHub破坏测试覆盖面地址解析、源码加载、依赖解析以及list、search、view、add四条命令路径都要有测试抽象克制在出现多个真实 provider 之前优先使用小的 source-reader 抽象而不是插件系统。这些约束解释了本文反复出现的ref 先解析成 SHA、文件与 include 同快照读取等设计它们共同服务于解析层无副作用 命令层读到一致快照这两个可测试性目标。十一、快速核对清单编写或审查一个 shadcn 源码注册表时可用以下清单逐项核对均出自 registry.md根registry.json是否含name与homepage是被include的文件则允许省略name/homepageinclude是否显式指向registry.json文件且无 URL、绝对路径、..条目files路径是否相对于声明它的注册表文件registry:file/registry:page是否提供了target源文件是否可独立复制粘贴无仅应用内部可用的隐式导入registryDependencies中裸名是否只用于官方条目本注册表内依赖是否用了正确的命名空间地址GitHub 依赖是否需要且正确地钉了#ref整张注册表内条目名是否唯一GitHub 注册表消费方是否按ref → SHA → 同快照读取的流程实现构建后用list/search/view/add --dry-run/registry validate五连验证。小结shadcn 注册表体系的本质是用一份声明式的registry.json描述安装器应该落哪些文件、装哪些依赖、写哪些 CSS 变量由 CLI 负责把地址解析、文件读取、依赖展开这些脏活做完。源码注册表面向作者真实文件 include模块化构建后注册表面向消费端public/r下的 JSON而 GitHub 仓库则以根registry.json为入口直接进入消费链路。掌握了地址方案的五种分类、依赖不继承 ref 的规则、以及ref 先解析为 commit SHA的快照一致性约束你就可以按 registry.md 与 cli.md 的规范编写出可被npx shadcnlatest全链路验证的分发注册表。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考