如何为Kumo开发一个新组件：脚手架、注册表与测试全流程详解

如何为Kumo开发一个新组件脚手架、注册表与测试全流程详解【免费下载链接】kumoCloudflares component library for building modern web applications.项目地址: https://gitcode.com/gh_mirrors/kumo5/kumoKumo 是 Cloudflare 开源的 React 组件库cloudflare/kumo基于 Base UI Tailwind CSS v4 构建内置一套完整的组件开发体系Plop 组件脚手架、机器可读的组件注册表Registry代码生成、以及 Vitest 自动化测试。本文将带你走通 Kumo 新组件开发全流程——从一键脚手架到 Variants 标准、注册表元数据生成再到单元测试与构建校验帮助新手快速上手 Kumo 组件库开发。一、认识 Kumo一个工程化拉满的 React 组件库Kumo 采用 pnpm monorepo 组织核心工作区包括packages/kumo组件库本体39 个 UI 组件ESM-only、按组件 tree-shakeablepackages/kumo-docs-astroAstro 构建的官方文档站演示示例会喂给注册表packages/kumo-figmaFigma 插件从源码同步设计令牌packages/kumo-screenshot-worker文档截图 Worker库的整体结构、目录职责与开发约定都记录在 packages/kumo/AGENTS.md 中是开发前最值得通读的一份地图。二、环境准备两条命令搭好 Kumo 开发环境克隆仓库后只需安装依赖并执行一次完整构建即可git clone https://gitcode.com/gh_mirrors/kumo5/kumo cd kumo pnpm install pnpm build 日常开发时可以用pnpm dev开启 watch 模式改动即自动重新打包。更多入门细节见 CONTRIBUTING.md。三、组件脚手架pnpm new:component 一键生成完整骨架Kumo 的脚手架由 plopfile.js 定义对应的 npm script 在 package.json 中声明pnpm new:component按提示输入组件名如my-widget脚手架会自动完成6 件事创建 3 个新文件基于 Handlebars 模板见 plop-templates/component.tsx.hbssrc/components/my-widget/my-widget.tsx—— 组件实现src/components/my-widget/index.ts—— 组件导出src/components/my-widget/my-widget.test.tsx—— 单元测试骨架见 component.test.tsx.hbs更新 3 个入口文件通过PLOP_INJECT_EXPORT、PLOP_INJECT_COMPONENT_ENTRY等标记注释精准插入plopfile.jssrc/index.ts —— 主 barrel 导出vite.config.ts —— 新增components/my-widget构建入口package.json —— 新增./components/my-widget导出路径含类型声明生成后即可通过两种方式导入import { MyWidget } from cloudflare/kumo; import { MyWidget } from cloudflare/kumo/components/my-widget; // 按需路径⚠️ 项目明确反模式手动创建组件文件会遗漏上述入口更新请务必使用pnpm new:component。四、编写组件Variants 标准与样式约定Kumo 对每个组件有一套被 lint 强制执行的Variants 标准规则kumo/enforce-variant-standard见 lint/enforce-variant-standard.js。组件文件必须导出三个对象完整规范见 src/components/AGENTS.md// 1. 机器可读的样式选项变体、尺寸、形状… export const KUMO_MY_WIDGET_VARIANTS { variant: { primary: { classes: bg-kumo-elevated, description: 主操作 } }, } as const; // 2. 默认值键必须引用上面的变体 export const KUMO_MY_WIDGET_DEFAULT_VARIANTS { variant: primary } as const; // 3. 可选Figma 插件元数据 export const KUMO_MY_WIDGET_STYLING { baseClasses: inline-flex ... } as const;样式铁律都有专门 lint 规则拦截✅ 只用语义化 tokenbg-kumo-base、text-kumo-default禁用原始 Tailwind 颜色kumo/no-primitive-colors✅禁用dark:前缀——明暗模式由 CSSlight-dark()自动切换kumo/no-tailwind-dark-variant✅ 类名合并一律用cn()工具className{cn(base-classes, className)}✅ 用forwardRef实现的组件必须设置displayName✅ Tailwind 类名必须静态可解析禁止leading-[${val}]这类动态拼接五、组件注册表从 TypeScript 类型到 AI 可消费的元数据Kumo 最有特色的设计是组件注册表构建时自动把每个组件的 Props、变体、示例代码编译成 JSON 元数据ai/component-registry.json Markdown Zod 校验 schema供 AI 工具和 CLI 消费。代码生成管线入口是 scripts/component-registry/index.ts流程为src/components/ 自动发现组件 ↓ ts-json-schema-generator 从 TS 类型推导 Props ↓ 富化Variants 描述 文档站 Demo 示例 子组件 ↓ 输出 ai/component-registry.{json,md} ai/schemas.ts手动触发生成的命令pnpm codegen:registry几个工程细节基于文件哈希的增量缓存未变组件直接跳过、8 路并行处理、类型推导失败时静默降级为仅变体元数据。注意ai/目录下的产物全部自动生成严禁手改——改源码CI 会重新生成。六、测试与验证单元测试 结构性校验 构建门禁Kumo 的测试体系分三层覆盖从组件行为正确到包结构正确的完整链路1️⃣ 组件单元测试Vitest happy-dom脚手架已生成测试骨架在生成的my-widget.test.tsx中补充断言后运行pnpm test浏览器级行为如弹窗动画、组合键交互则编写*.browser.test.tsx用pnpm test:browser在 Playwright 中执行。配置见 vitest.config.ts。2️⃣ 结构性导出校验tests/imports/export-path-validation.test.ts 会校验package.json的 exports、vite.config.ts构建入口、实际产物三者一致——这正是脚手架自动改这 3 个文件的原因。单独运行pnpm test:exports。3️⃣ 完整构建三步管线pnpm build构建依次执行注册表代码生成 → CSS 处理css-build.ts→ Vite 双 pass 打包JS 产物 独立 d.ts 声明每个 chunk 自动注入use client前缀以兼容 RSC。七、避坑清单Kumo 组件开发的常见反模式反模式后果正确做法手动创建组件文件遗漏 index/vite/package.json 更新pnpm new:component手写ai/component-registry.*构建时被覆盖改组件源码CI 自动生成硬编码颜色 / 使用dark:破坏主题体系使用kumo-*语义 token裸className字符串丢失调用方透传样式cn(base, className)缺少displayNameReact DevTools 显示异常forwardRef 后设置八、收尾提交前别忘了 Changeset测试与构建全部通过后为变更添加 changeset用于自动生成 changelog 与版本pnpm changeset git add .changeset/*.md之后按 CONTRIBUTING.md 的 PR 流程提交即可——kumo仓库强制 squash merge并会在合并后由 Changesets 机器人自动发布版本。总结Kumo 新组件开发 一条pnpm new:component脚手架命令 遵守 Variants 标准编码 pnpm codegen:registry生成注册表 pnpm test pnpm build双重验证。整套流程高度自动化让开发者把精力集中在组件本身的设计与实现上。【免费下载链接】kumoCloudflares component library for building modern web applications.项目地址: https://gitcode.com/gh_mirrors/kumo5/kumo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考