shadcn-svelte 自定义组件注册表registry.json 模式完全指南【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelteregistry.json是 shadcn-svelte 生态中用于定义**自定义组件注册表component registry**的根配置文件你在其中声明注册表元信息、注册表包含的全部组件条目以及构建时需要的路径别名和依赖覆盖规则。本文以 registry-json 文档 为主线结合仓库内 JSON Schema 定义 与 CLI 构建实现逐字段讲解如何编写一份可被shadcn-svelte registry build正确解析、并能让用户通过shadcn-svelte add一键安装的自定义注册表配置读完即可动手搭建属于你自己的组件分发管道。registry.json 在整个注册表体系中的位置在 shadcn-svelte 的组件分发体系中存在两层 JSON 规范二者职责不同容易混淆文件职责由谁产出registry.json注册表的源清单描述注册表自身信息与待构建的条目由注册表维护者手写放在项目根目录registry-item.json单个注册表条目的分发产物包含可直接安装的文件内容、目标路径、依赖等由 CLIregistry build命令根据registry.json自动生成二者分别对应仓库中的两份 Schemaregistry.json Schema 与 registry-item.json Schema。用一句话概括两者的关系registry.json是构建期输入registry-item.json是安装期输出用户执行add命令时实际消费的是后者。补充说明如果你不使用shadcn-svelteCLI 构建注册表完全可以跳过registry.json只要你的构建系统能直接产出符合 registry-item 规范 的 JSON 文件即可参见 Getting Started。最小可用的 registry.json一份最简配置如下它声明了一个名为shadcn-svelte的注册表并包含一个hello-world条目{ $schema: https://shadcn-svelte.com/schema/registry.json, name: shadcn-svelte, homepage: https://shadcn-svelte.com, items: [ { name: hello-world, type: registry:block, title: Hello World, description: A simple hello world component., files: [ { path: src/lib/registry/blocks/hello-world/hello-world.svelte, type: registry:component } ] } ] }其中顶层字段name、homepage、items是必填项在 Schema 的required数组中被明确列出$schema、aliases、overrideDependencies为可选项并且 Schema 设置了additionalProperties: false意味着不能出现任何未定义的顶层字段否则构建时校验会失败。顶层字段逐一解析$schema声明校验模式$schema用于指定registry.json文件所遵循的 JSON Schema便于编辑器如 VS Code提供自动补全与校验{ $schema: https://shadcn-svelte.com/schema/registry.json }在 CLI 源码中$schema是可选的见 schema.ts 的 registrySchema 定义。该字段本身不参与构建逻辑只服务于开发体验。name注册表名称name用于指定注册表的名称会被用于data属性等元数据场景{ name: acme }homepage注册表主页homepage指定注册表的主页地址同样用于data属性与其他元数据{ homepage: https://acme.com }从 Schema 定义 看name与homepage均为字符串类型语义上应当是全局唯一的注册表标识与官方站点地址。items注册表条目清单items是注册表的核心数组中的每个元素都必须实现 registry-item 模式规范{ items: [ { name: hello-world, type: registry:block, title: Hello World, description: A simple hello world component., files: [ { path: src/lib/registry/blocks/hello-world/hello-world.svelte, type: registry:component } ] } ] }每个条目可用的字段依据 registry.json Schema 与 registry-item Schema字段类型必填说明namestring是条目唯一标识在整个注册表中必须唯一typestring是条目类型决定其被解析到项目中的目标路径titlestring否人类可读的短标题descriptionstring否条目简介可比 title 更详细authorstring否作者推荐格式username url至少 2 个字符dependenciesstring[]否条目需要的 npm 依赖devDependenciesstring[]否条目需要的 npm 开发依赖registryDependenciesstring[]否依赖的其他注册表条目详见下文metaobject否任意键值对元数据filesobject[]是文件清单指导build命令如何定位与解析注册表源码文件cssVarsobject否主题 CSS 变量theme/light/darkcssobject否要注入项目 CSS 文件的规则支持layer、keyframes、utility等fontobject否字体元数据仅registry:font条目使用注意在registry.json的条目中files中的每个文件对象必填path与typetarget可选而在生成的registry-item.json中则反过来文件对象必填content、type、target。这正是源清单与分发产物的差异所在。条目的 type 类型条目的type决定它在用户项目中的安装位置。完整枚举如下取自 registry-item Schema 及 registry-item 文档类型适用场景registry:block多文件复杂组件复杂区块registry:component简单组件registry:lib库代码与工具函数registry:hookSvelte hooks.svelte.ts/.svelte.jsregistry:uiUI 组件与单文件原语registry:page页面或基于文件的路由registry:file杂项文件registry:style注册表样式如new-yorkregistry:theme主题registry:base基础样式/调色板registry:font字体条目registry:example示例内部用途registry:internal内部用途files 中的文件类型files数组中每个文件的type字段取值范围比条目类型略窄不支持registry:example与registry:internal包括registry:lib、registry:block、registry:component、registry:ui、registry:hook、registry:page、registry:file、registry:theme、registry:style、registry:item、registry:base、registry:font。文件类型会影响构建时对目标路径的推导见下文构建流程。registryDependencies 的四种引用方式registryDependencies声明条目依赖的其他注册表条目支持四种写法详见 registry-item 文档shadcn-svelte 官方条目直接写组件名如[button, input, select]会解析到官方注册表对应条目远程 URL写完整 URL如[https://example.com/r/hello-world.json]本地别名仅使用 CLI 构建时在registry.json中写local:前缀如[local:stepper]CLI 构建时会自动转换成相对路径./stepper.json相对路径非 CLI 场景直接写相对于当前条目的路径如[./stepper.json]。其中local:转换由 build.ts 中的 transformLocal 函数 实现它用正则^local:(.*)匹配并将local:stepper改写为./stepper.json。这样你可以在同一个注册表内部复用自己构建的组件而无需硬编码最终 URL。aliases构建期的导入路径转换aliases定义了注册表内部导入路径在用户安装时如何被转换。这些别名必须与你在注册表源码中实际使用的导入写法保持一致。例如假设你的注册表组件源码是script langts import { Button } from /lib/registry/ui/button/index.js; import { cn } from /lib/utils.js; /script那么registry.json中就应该提供匹配的别名{ aliases: { lib: /lib, // Matches your internal imports ui: /lib/registry/ui, // Matches your internal imports components: /lib/registry/components, // Matches your internal imports utils: /lib/utils, // Matches your internal imports hooks: /lib/hooks // Matches your internal imports } }用户在安装你的组件时这些路径会依据其项目components.json中的aliases配置被替换。你在registry.json中定义的别名是源路径即构建时被替换的对象。如果不指定aliasesCLI 会使用以下默认值源码位于 constants.ts{ aliases: { lib: $lib/registry/lib, // For internal library code ui: $lib/registry/ui, // For UI components components: $lib/registry/components, // For component-specific code utils: $lib/utils, // For utility functions hooks: $lib/registry/hooks // For reactive state and logic (.svelte.js|ts) } }底层转换原理构建时transformAliases 函数 遍历固定的五个别名键components、ui、hooks、utils、lib将源码中出现的别名路径全部替换为标准化占位符如$UTILS$、$UI$、$LIB$。你在官方注册表产物中能直接观察到这一机制的痕迹——例如 button.json 中的文件内容包含import { cn, type WithElementRef } from $UTILS$.js$UTILS$就是构建期留下的占位符。当用户执行add命令时CLI 再根据用户项目的components.json中的aliasesui、utils、hooks、lib、components将这些占位符替换为最终路径转换逻辑见 transform-imports.ts。建议注册表源码中统一使用$lib/...或自定义别名导入并让registry.json的aliases与之严格一致这样构建产物才能被正确改写避免用户安装后出现模块找不到的错误。overrideDependencies强制覆盖依赖版本overrideDependencies允许你为某些依赖强制指定版本范围覆盖shadcn-svelte registry build从你项目package.json中自动检测到的版本。常见用途使用最新预发布版本overrideDependencies: [paneforgenext]锁定到指定版本overrideDependencies: [dep1.5.0]其工作方式如下。假设你的注册表package.json中依赖如下// Your registrys package.json { dependencies: { paneforge: 1.0.0-next.1 } }构建时若声明了overrideDependencies: [paneforgenext]当用户安装你的组件时会自动解析使用最新的next版本而不是你 package.json 中锁定的1.0.0-next.1{ dependencies: { paneforge: 1.0.0-next.1, // overrideDependencies: [] paneforge: 1.0.0-next.5 // overrideDependencies: [paneforgenext] } }警告覆盖依赖可能导致版本冲突若管理不当会引入不兼容问题此选项应谨慎使用仅在确有必要时启用。底层实现在 build.ts 的 runBuild 函数 中构建时会先调用resolveProjectDeps解析项目依赖然后对overrideDependencies数组中的每一项执行overrideDep通过parseDependency解析出依赖名替换dependencies与devDependencies两张表中的对应版本条目原版本条目被删除、新版本条目连同其 peer 依赖一并写入。从代码看覆盖发生在依赖自动检测之前因此会同时影响后续按文件扫描得到的依赖结果。构建流程从 registry.json 到可安装产物理解了字段含义后完整构建链路如下对应 Getting Started 中的操作步骤创建组件源码按registry/[NAME]/...目录结构放置组件并在registry.json的items[].files[].path中正确指向它们编写 registry.json声明$schema、name、homepage、items并按需配置aliases、overrideDependencies执行构建安装 CLI 后运行pnpm shadcn-svelte registry build可在package.json中注册registry:build: pnpm shadcn-svelte registry build脚本校验与产出CLI 先用 registrySchema 校验registry.json然后生成两类文件到static/r目录默认输出路径可用--output参数修改index.json注册表索引每个条目附带relativeUrl即[name].json[item-name].json每个条目的registry-item.json分发产物文件内容为经过别名转换后的源码目标路径按条目/文件类型推导多文件条目或registry:page/registry:ui/registry:file类型会嵌套到[item-name]/子目录下。你可以直接查看仓库中 index.json 产物 与 button.json 产物 来理解最终输出形态。构建完成后将项目部署到公网即可让其他开发者使用shadcn-svelte add https://your-domain/r/hello-world.json安装你的组件。结语一份可落地的自定义注册表清单构建自定义注册表时请对照以下要点自查顶层name、homepage、items三字段必填且不要添加 Schema 之外的顶层字段每个条目必须提供name、type与files文件对象在registry.json中必填pathtype尽量把源码组织在components、hooks、lib目录下便于路径推导与维护在registryDependencies中完整列出所有依赖跨注册表内部复用使用local:前缀让aliases与源码导入写法保持一致否则安装后导入路径无法正确转换仅在确有必要时使用overrideDependencies并注意版本兼容性。依照本文与 registry.json Schema、registry-item 规范、注册表入门指南你就能构建出一套可被 CLI 解析、可被社区安装的 shadcn-svelte 组件注册表。【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelte创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 shadcn-svelte 自定义组件注册表：registry.json 模式完全指南
shadcn-svelte 自定义组件注册表registry.json 模式完全指南【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelteregistry.json是 shadcn-svelte 生态中用于定义**自定义组件注册表component registry**的根配置文件你在其中声明注册表元信息、注册表包含的全部组件条目以及构建时需要的路径别名和依赖覆盖规则。本文以 registry-json 文档 为主线结合仓库内 JSON Schema 定义 与 CLI 构建实现逐字段讲解如何编写一份可被shadcn-svelte registry build正确解析、并能让用户通过shadcn-svelte add一键安装的自定义注册表配置读完即可动手搭建属于你自己的组件分发管道。registry.json 在整个注册表体系中的位置在 shadcn-svelte 的组件分发体系中存在两层 JSON 规范二者职责不同容易混淆文件职责由谁产出registry.json注册表的源清单描述注册表自身信息与待构建的条目由注册表维护者手写放在项目根目录registry-item.json单个注册表条目的分发产物包含可直接安装的文件内容、目标路径、依赖等由 CLIregistry build命令根据registry.json自动生成二者分别对应仓库中的两份 Schemaregistry.json Schema 与 registry-item.json Schema。用一句话概括两者的关系registry.json是构建期输入registry-item.json是安装期输出用户执行add命令时实际消费的是后者。补充说明如果你不使用shadcn-svelteCLI 构建注册表完全可以跳过registry.json只要你的构建系统能直接产出符合 registry-item 规范 的 JSON 文件即可参见 Getting Started。最小可用的 registry.json一份最简配置如下它声明了一个名为shadcn-svelte的注册表并包含一个hello-world条目{ $schema: https://shadcn-svelte.com/schema/registry.json, name: shadcn-svelte, homepage: https://shadcn-svelte.com, items: [ { name: hello-world, type: registry:block, title: Hello World, description: A simple hello world component., files: [ { path: src/lib/registry/blocks/hello-world/hello-world.svelte, type: registry:component } ] } ] }其中顶层字段name、homepage、items是必填项在 Schema 的required数组中被明确列出$schema、aliases、overrideDependencies为可选项并且 Schema 设置了additionalProperties: false意味着不能出现任何未定义的顶层字段否则构建时校验会失败。顶层字段逐一解析$schema声明校验模式$schema用于指定registry.json文件所遵循的 JSON Schema便于编辑器如 VS Code提供自动补全与校验{ $schema: https://shadcn-svelte.com/schema/registry.json }在 CLI 源码中$schema是可选的见 schema.ts 的 registrySchema 定义。该字段本身不参与构建逻辑只服务于开发体验。name注册表名称name用于指定注册表的名称会被用于data属性等元数据场景{ name: acme }homepage注册表主页homepage指定注册表的主页地址同样用于data属性与其他元数据{ homepage: https://acme.com }从 Schema 定义 看name与homepage均为字符串类型语义上应当是全局唯一的注册表标识与官方站点地址。items注册表条目清单items是注册表的核心数组中的每个元素都必须实现 registry-item 模式规范{ items: [ { name: hello-world, type: registry:block, title: Hello World, description: A simple hello world component., files: [ { path: src/lib/registry/blocks/hello-world/hello-world.svelte, type: registry:component } ] } ] }每个条目可用的字段依据 registry.json Schema 与 registry-item Schema字段类型必填说明namestring是条目唯一标识在整个注册表中必须唯一typestring是条目类型决定其被解析到项目中的目标路径titlestring否人类可读的短标题descriptionstring否条目简介可比 title 更详细authorstring否作者推荐格式username url至少 2 个字符dependenciesstring[]否条目需要的 npm 依赖devDependenciesstring[]否条目需要的 npm 开发依赖registryDependenciesstring[]否依赖的其他注册表条目详见下文metaobject否任意键值对元数据filesobject[]是文件清单指导build命令如何定位与解析注册表源码文件cssVarsobject否主题 CSS 变量theme/light/darkcssobject否要注入项目 CSS 文件的规则支持layer、keyframes、utility等fontobject否字体元数据仅registry:font条目使用注意在registry.json的条目中files中的每个文件对象必填path与typetarget可选而在生成的registry-item.json中则反过来文件对象必填content、type、target。这正是源清单与分发产物的差异所在。条目的 type 类型条目的type决定它在用户项目中的安装位置。完整枚举如下取自 registry-item Schema 及 registry-item 文档类型适用场景registry:block多文件复杂组件复杂区块registry:component简单组件registry:lib库代码与工具函数registry:hookSvelte hooks.svelte.ts/.svelte.jsregistry:uiUI 组件与单文件原语registry:page页面或基于文件的路由registry:file杂项文件registry:style注册表样式如new-yorkregistry:theme主题registry:base基础样式/调色板registry:font字体条目registry:example示例内部用途registry:internal内部用途files 中的文件类型files数组中每个文件的type字段取值范围比条目类型略窄不支持registry:example与registry:internal包括registry:lib、registry:block、registry:component、registry:ui、registry:hook、registry:page、registry:file、registry:theme、registry:style、registry:item、registry:base、registry:font。文件类型会影响构建时对目标路径的推导见下文构建流程。registryDependencies 的四种引用方式registryDependencies声明条目依赖的其他注册表条目支持四种写法详见 registry-item 文档shadcn-svelte 官方条目直接写组件名如[button, input, select]会解析到官方注册表对应条目远程 URL写完整 URL如[https://example.com/r/hello-world.json]本地别名仅使用 CLI 构建时在registry.json中写local:前缀如[local:stepper]CLI 构建时会自动转换成相对路径./stepper.json相对路径非 CLI 场景直接写相对于当前条目的路径如[./stepper.json]。其中local:转换由 build.ts 中的 transformLocal 函数 实现它用正则^local:(.*)匹配并将local:stepper改写为./stepper.json。这样你可以在同一个注册表内部复用自己构建的组件而无需硬编码最终 URL。aliases构建期的导入路径转换aliases定义了注册表内部导入路径在用户安装时如何被转换。这些别名必须与你在注册表源码中实际使用的导入写法保持一致。例如假设你的注册表组件源码是script langts import { Button } from /lib/registry/ui/button/index.js; import { cn } from /lib/utils.js; /script那么registry.json中就应该提供匹配的别名{ aliases: { lib: /lib, // Matches your internal imports ui: /lib/registry/ui, // Matches your internal imports components: /lib/registry/components, // Matches your internal imports utils: /lib/utils, // Matches your internal imports hooks: /lib/hooks // Matches your internal imports } }用户在安装你的组件时这些路径会依据其项目components.json中的aliases配置被替换。你在registry.json中定义的别名是源路径即构建时被替换的对象。如果不指定aliasesCLI 会使用以下默认值源码位于 constants.ts{ aliases: { lib: $lib/registry/lib, // For internal library code ui: $lib/registry/ui, // For UI components components: $lib/registry/components, // For component-specific code utils: $lib/utils, // For utility functions hooks: $lib/registry/hooks // For reactive state and logic (.svelte.js|ts) } }底层转换原理构建时transformAliases 函数 遍历固定的五个别名键components、ui、hooks、utils、lib将源码中出现的别名路径全部替换为标准化占位符如$UTILS$、$UI$、$LIB$。你在官方注册表产物中能直接观察到这一机制的痕迹——例如 button.json 中的文件内容包含import { cn, type WithElementRef } from $UTILS$.js$UTILS$就是构建期留下的占位符。当用户执行add命令时CLI 再根据用户项目的components.json中的aliasesui、utils、hooks、lib、components将这些占位符替换为最终路径转换逻辑见 transform-imports.ts。建议注册表源码中统一使用$lib/...或自定义别名导入并让registry.json的aliases与之严格一致这样构建产物才能被正确改写避免用户安装后出现模块找不到的错误。overrideDependencies强制覆盖依赖版本overrideDependencies允许你为某些依赖强制指定版本范围覆盖shadcn-svelte registry build从你项目package.json中自动检测到的版本。常见用途使用最新预发布版本overrideDependencies: [paneforgenext]锁定到指定版本overrideDependencies: [dep1.5.0]其工作方式如下。假设你的注册表package.json中依赖如下// Your registrys package.json { dependencies: { paneforge: 1.0.0-next.1 } }构建时若声明了overrideDependencies: [paneforgenext]当用户安装你的组件时会自动解析使用最新的next版本而不是你 package.json 中锁定的1.0.0-next.1{ dependencies: { paneforge: 1.0.0-next.1, // overrideDependencies: [] paneforge: 1.0.0-next.5 // overrideDependencies: [paneforgenext] } }警告覆盖依赖可能导致版本冲突若管理不当会引入不兼容问题此选项应谨慎使用仅在确有必要时启用。底层实现在 build.ts 的 runBuild 函数 中构建时会先调用resolveProjectDeps解析项目依赖然后对overrideDependencies数组中的每一项执行overrideDep通过parseDependency解析出依赖名替换dependencies与devDependencies两张表中的对应版本条目原版本条目被删除、新版本条目连同其 peer 依赖一并写入。从代码看覆盖发生在依赖自动检测之前因此会同时影响后续按文件扫描得到的依赖结果。构建流程从 registry.json 到可安装产物理解了字段含义后完整构建链路如下对应 Getting Started 中的操作步骤创建组件源码按registry/[NAME]/...目录结构放置组件并在registry.json的items[].files[].path中正确指向它们编写 registry.json声明$schema、name、homepage、items并按需配置aliases、overrideDependencies执行构建安装 CLI 后运行pnpm shadcn-svelte registry build可在package.json中注册registry:build: pnpm shadcn-svelte registry build脚本校验与产出CLI 先用 registrySchema 校验registry.json然后生成两类文件到static/r目录默认输出路径可用--output参数修改index.json注册表索引每个条目附带relativeUrl即[name].json[item-name].json每个条目的registry-item.json分发产物文件内容为经过别名转换后的源码目标路径按条目/文件类型推导多文件条目或registry:page/registry:ui/registry:file类型会嵌套到[item-name]/子目录下。你可以直接查看仓库中 index.json 产物 与 button.json 产物 来理解最终输出形态。构建完成后将项目部署到公网即可让其他开发者使用shadcn-svelte add https://your-domain/r/hello-world.json安装你的组件。结语一份可落地的自定义注册表清单构建自定义注册表时请对照以下要点自查顶层name、homepage、items三字段必填且不要添加 Schema 之外的顶层字段每个条目必须提供name、type与files文件对象在registry.json中必填pathtype尽量把源码组织在components、hooks、lib目录下便于路径推导与维护在registryDependencies中完整列出所有依赖跨注册表内部复用使用local:前缀让aliases与源码导入写法保持一致否则安装后导入路径无法正确转换仅在确有必要时使用overrideDependencies并注意版本兼容性。依照本文与 registry.json Schema、registry-item 规范、注册表入门指南你就能构建出一套可被 CLI 解析、可被社区安装的 shadcn-svelte 组件注册表。【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelte创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考