新闻详情

新闻详情

首页 / 资讯中心 / 详情

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

发布时间:2026/11/16 21:59:20来源:尧图网络
如何为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),仅供参考
网站建设高端定制企业官网
RELATED

相关资讯

更多精彩内容,欢迎继续阅读

较早相关资讯

最新相关资讯

【外设】之大彩串口显示屏 2026/11/15 4:54:16

【外设】之大彩串口显示屏

大彩串口屏初步使用 1 .官网下载 STM32 屏幕 GUI 设计资料 http://www.gz-dc.com/category/typeid/4112 找到 STM32 Keil 工程,移植相关代码因项目而异进行移植,由于项目简单,本人只对用到的指令接口进行修改。 比如:注意事项&…

阅读更多 →
无法下载Windows系统iso文件 2026/11/15 2:04:12

无法下载Windows系统iso文件

当我遇到这个问题的时候,我打开了一个网站: 登录 然后我打算下载的时候: 突然那个官方的连接就可以下载了:

阅读更多 →
【清华代码熊】DeepSeek V4.1 Flash 后训练详解 2026/11/16 19:23:38

【清华代码熊】DeepSeek V4.1 Flash 后训练详解

📌 上期解析了 DeepSeek V4.1 Flash 模型架构改进,本期解析 DeepSeek V4.1 Flash 预训练/后训练技术: 🌟 预训练:45T 文本 多模态混合语料、直接训练 sparse attention(取消 DeepSeek V4 的 dense 冷启动&…

阅读更多 →
Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ... 2026/11/16 6:47:19

Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ...

文章主要内容和创新点 主要内容 本文聚焦于多模态大语言模型(MLLM)强化学习(RL)训练中的效率问题,提出了一个名为Shuffle-R1的框架。研究发现,当前RL训练存在两个关键缺陷: 优势值坍缩(Advantage Collapsing):批次中大多数优势值集中在零附近,导致有效梯度信号被淹…

阅读更多 →
PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction 2026/11/14 16:35:50

PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction

一、文章主要内容总结 本文聚焦于利用大型语言模型(LLMs)实现个人身份信息(PII)脱敏的研究,旨在解决传统脱敏方法(如基于规则的系统、领域特定命名实体识别(NER)模型)泛化能力差、跨格式/跨语境适应性弱的问题。 研究通过全面评估多种LLM架构(包括密集型LLM(D-LLM…

阅读更多 →
LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model 2026/11/16 17:28:18

LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model

文章主要内容和创新点 主要内容 本文聚焦于二进制图像-文本相关性评估任务(判断图像与文本“相关”或“不相关”),针对该任务中文本格式多样、相关性定义随场景变化等挑战,提出了基于多模态大语言模型(MLLM)的解决方案LLaVA-RE。 模型设计:LLaVA-RE基于LLaVA 1.5架构,…

阅读更多 →

今日资讯

本周资讯

本月资讯

看完文章仍有疑问?

联系尧图顾问,获取一对一建站咨询

立即免费咨询 📞 400-888-8888
📞 ✉