@cloudflare/kumo (英语)
Cloudflare用于构建现代网络应用的组件库.
安装
pnpm add @cloudflare/kumo
同伴依赖关系
Kumo 需要以下对等关系:
pnpm add react react-dom @phosphor-icons/react
构成部分文件
Kumo包括一个内置的CLI
npx @cloudflare/kumo ls # List all components
npx @cloudflare/kumo doc Button # Get component documentation
npx @cloudflare/kumo docs # Get all component docs
"CLI"从 ai/component-registry.json (由TypeScript类型+演示示例生成).
使用量
导入组件
// Main package import
import { Button, Input, Surface } from "@cloudflare/kumo";
// Granular imports (recommended for tree-shaking)
import { Button } from "@cloudflare/kumo/components/button";
导入样式
用于 Tailwind CSS 用户
重要内容: 尾风 CSS v4 不扫描 node_modules/ 默认。 您必须添加一个 @source 指令使Tailwind能够发现Kumo组件所使用的工具类. 没有此选项, 组件可能会被缺少的样式所渲染( 例如, 未居中对话框) .
在您的主 CSS 文件( 例如 ) 中 . app.css:
@source "../node_modules/@cloudflare/kumo/dist/**/*.{js,jsx,ts,tsx}";
@import "@cloudflare/kumo/styles/tailwind";
@import "tailwindcss";
进口订单事项 —— 说
@cloudflare/kumo/styles一定要来 在此之前@import "tailwindcss"所以库莫@theme符号先被注册 .
说明: 这个
@source路径相对于您的 CSS 文件 。 根据您的项目结构调整它—— 例如, 如果您的CSS 处于src/styles/你也许需要../../node_modules/@cloudflare/kumo/dist/**/*.{js,jsx,ts,tsx}。 。 。 .
或者,您可以使用默认样式导出( E)@cloudflare/kumo/styles等值为 styles/tailwind。 。 。 .
如果你是的话 没有 使用 Tailwind CSS, 取而代之使用独立架构(见下文)- 否 @source 需要指令.
对于非泰尔风用户( 单独)
import "@cloudflare/kumo/styles/standalone";
这导入了完整编译的包含所有 Tailwind 公用设施和 Kumo 风格的 CSS 文件 。 不需要尾风配置!
独立内容包括:
- Kumo 组件使用的所有 Tailwind 工具类
- Kumo 组件样式
- 暗模式支持( 通过
data-mode="dark"属性) - 所有动画和键框
- 反应型公用事业
说明: 独立的CSS是精密化和优化的,但将大于Tailwind版本,因为它包括所有公用事业.
基础 UI 初级
Kumo 捆绑 基础UI 并再出口所有原始物以供高级使用:
// Barrel import - imports all primitives (convenient but larger bundle)
import { Popover, Slider, Accordion } from "@cloudflare/kumo/primitives";
// Granular imports - tree-shakeable, smaller bundles (recommended)
import { Popover } from "@cloudflare/kumo/primitives/popover";
import { Slider } from "@cloudflare/kumo/primitives/slider";
import { Accordion } from "@cloudflare/kumo/primitives/accordion";
说明: 当有库莫组件时,更倾向于使用它。 初级产品是库莫尚未使用的自定义部件或需要精细控制的情况.
性能提示 : 使用颗粒进口(
@cloudflare/kumo/primitives/{name}),以更好的树摇和更小的捆绑尺寸.
更新原始内容
初级出口自动由Base UI生成. 升级后 @base-ui/react数字 :
# Regenerate primitive files to sync with new Base UI version
pnpm build:primitives
# Review changes (new/removed primitives)
git diff src/primitives/
# Commit if primitives changed
git add src/primitives/ package.json
git commit -m "chore: update primitives for [email protected]"
这个 build:primitives 脚本 :
- 生成单个原始文件
src/primitives/*.ts - 更新枪管导出于
src/primitives/index.ts - 更新
package.json有颗粒导出路径 - 每次建设之前通过
prebuild脚本
校验构建输出
建成后,验证原始人输出:
# Run post-build validation (checks dist/ structure)
pnpm validate:build
此验证 :
- 所有原始的JS文件都存在于
dist/primitives/ - 所有类型定义都存在于
dist/src/primitives/ - 碱基UI被捆绑( 不外部化)
- 导入路径引用捆绑模块
- 存在原始地图
发展
关于综合贡献文件,见 一般事务人员(其他职等)。 。 。 .
创建新组件
使用脚手架工具快速创建所有需要的文件和配置的新组件 :
# Create a new component
pnpm new-component
# Or use the shorthand
pnpm new
它创造了什么:
- 组件文件 :
src/components/{name}/{name}.tsx - 索引文件 :
src/components/{name}/index.ts - 测试文件 :
src/components/{name}/{name}.test.tsx
它更新的内容:
src/index.ts- 添加组件导出vite.config.ts- 添加构建条目package.json- 添加导出配置
示例
? Component name: Alert Banner
✅ Component scaffolded successfully!
📁 Files created:
- src/components/alert-banner/alert-banner.tsx
- src/components/alert-banner/index.ts
- src/components/alert-banner/alert-banner.test.tsx
脚手架工具自动处理命名 - 输入任何格式( 空间, PascalCase, kebab- case) , 它会适当转换 .
创建新块
Blocks是更高层次的组件,由多个基础组件组成来创建共同的页面模式. 使用块脚手架工具 :
# Create a new block
pnpm new-block
它创造了什么:
- 块文件 :
src/blocks/{name}/{name}.tsx - 索引文件 :
src/blocks/{name}/index.ts - 测试文件 :
src/blocks/{name}/{name}.test.tsx
它更新的内容:
src/index.ts- 添加块导出vite.config.ts- 添加构建条目package.json- 添加导出配置
块是构成多块基元件的更高级组件. 见 一般事务人员(其他职等) 关于区块的详细文件.
发展流动
监视构建模式
测试实际文件站点或消耗性应用中的组件:
开始监视构建 :
pnpm dev
以监视模式运行 Vite, 并优化快速重建 :
- 重建时间(10x快于生产建设)
- 开发中跳过微缩
- 递增类型脚本汇编
- 选择性文件监视( ignores 测试)
- 对照生产结构产出验证组件
使用文件网址:
终端 1 (本目录) :
pnpm dev
2号航站楼(来自工作空间根或kumo-docs):
cd ../kumo-docs
pnpm dev
编辑组件时:
- Kumo 自动重建( ~ 400ms)
- 刷新浏览器以查看 Docs 站点的变化
- 对照实际构建产出验证更改
构建模式 :
pnpm dev- 开发模式(快速、优化以进行迭代)pnpm build- 生产模式(全面优化、精密化、CSS加工)
测试
该包包括全面的进口验证测试,以确保所有部件都适当出口并可以消费.
运行测试 :
# Watch mode
pnpm test
# Single run
pnpm test:run
# With UI
pnpm test:ui
# With coverage
pnpm test:coverage
测试的是什么:
- 从主条目可导入的所有组件 :
import { Component } from "@cloudflare/kumo" - 所有可通过深度进口进口的部件:
import { Component } from "@cloudflare/kumo/components/component-name" - 从主条目导入的所有块 :
import { Block } from "@cloudflare/kumo" - 可通过深度进口导入的所有区块:
import { Block } from "@cloudflare/kumo/blocks/block-name" - Packet.json 输出与实际组件和块同步
- 导出路径和格式正确
- 构建配置一致性
零维护: 测试会从文件系统自动发现组件和块并对照pack.json进行验证. 在添加新项目时,用精确的代码片段来固定配置的测试会失败.
Beta 发布
Beta发布允许您在发布到制作前测试更改. Beta版本是自动为拉出请求而创建的并包括承诺散列以进行识别.
自动β释放
Beta 发布会自动被触发,以通过 GitHub 动作(.github/workflows/package-preview-pr.yml:
工作流程配置 :
- 工作流程数字 :
package-preview-pr.yml - 触发器: 将更改的请求拉入
packages/kumo/**或者说.changeset/** - 依赖关系: 要求更改器存在
@cloudflare/kumo
流程 :
- 校验: 确保更改程序存在
@cloudflare/kumo - 版本: 运行
pnpm run version:beta- 待更改的消费
- 附录
-beta.{commit-hash}改为版本编号
- 构建: 运行
pnpm --filter @cloudflare/kumo build - 发布: 用 npm 发布
beta标签 - 通知: 张贴带有安装指令的PR注释
必需的秘密 :
NPM_TOKEN: npm 注册的认证GITHUB_TOKEN: 用于张贴 PR 注释(内置)
Beta 版本格式
Beta 版本遵循此模式 :
{base-version}-beta.{commit-hash}
例如: 0.1.0-beta.a1b2c3d
安装 beta 版本
当一个β发布时,PR会包含一个带有安装指令的评论:
# Install the specific beta version
npm install @cloudflare/[email protected]
# Or with pnpm
pnpm add @cloudflare/[email protected]
测试 Beta 释放
- 创建 PR: 以更改列表提交更改
- 等着Beta: beta 任务在更改后自动运行
- 安装 beta: 使用 PR 注释中的版本
- 测试更改: 校验工程中的功能
- 合并: 测试后, 将 PR 合并为生产释放
更改设置校验
所有有更改的拉动请求 packages/kumo/ 必须包含更改列表 :
# Create a changeset
pnpm changeset
- 选择
@cloudflare/kumo提示时 - 选择更改类型 :
patch, (中文(简体) ),minor,或major - 写清楚的描述什么改变了
CI会在允许β发布之前自动验证一个更改et的存在.
生产释放量
此软件包使用 更改 用于版本管理和自动发布.
创建释放
-
检查已有的更改数字 :
# List any pending changesets ls .changeset/*.md 2>/dev/null | grep -v "README\|USAGE" || echo "No pending changesets" -
创建更改列表 用于修改(如有必要):
pnpm changeset- 选择
@cloudflare/kumo从列表中 - 选择更改类型 :
patch, (中文(简体) ),minor,或major - 写清楚的描述什么改变了
- 这创造了一个
.changeset/*.md描述更改的文件
- 选择
释放工作流程
- 发展: 修改组件或块
- 更改集: 创建描述这些变化的更改器
- 审查: 提交带有更改和更改的 PR et
- Beta 测试: 测试向 PR 发布的β 版本
- 合并: 将 PR 合并到主分支
- 释放: 运行生产释放过程
生产释放工艺
出版发行版:
# 1. Ensure you're on main branch with latest changes
git checkout main
git pull
# 2. Version all packages (consumes changesets)
pnpm version
# 3. Build all packages
pnpm build:all
# 4. Publish to npm
pnpm release
这将:
- 更新
package.json带有新版本 - 生成/更新
CHANGELOG.md - 删除已消耗的更改et文件
- 发布到 npm 注册
- 创建 git 标签
释放后
出版后:
-
提交版本更改数字 :
git add . git commit -m "chore: release @cloudflare/kumo@{version}" git push -
推动标签数字 :
git push --tags -
校验出版物数字 :
npm view @cloudflare/kumo versions
语义版本
遵循语义版本指南 :
- 补丁 (单位:千美元)
0.0.1:错误修正、小组件更新、样式调整 - 次要 (单位:千美元)
0.1.0: 新组件,新特性,倒向相容的变化 - 少校 (单位:千美元)
1.0.0: 正在中断更改, 删除组件, API 更改
发布注释
更改器自动生成 :
- 更新
package.json版本 CHANGELOG.md带有发布注释- 每次发行的 Git 标签
变换日志包含所有变换et描述,提供清晰的文档,说明每版中的变化.
解决问题
共同问题
更改设置校验失败
如果 CI 以更改et 验证错误失败 :
- 检查更改器是否存在运行
ls .changeset/*.md以查看待决更改 - 创建更改列表运行
pnpm changeset选择@cloudflare/kumo - 校验更改对象正确包: 打开更改et文件并确保包括
@cloudflare/kumo - 提交更改: 将更改列表文件添加到您的分支
Beta 发布失败
如果β释放任务失败:
- 检查构建: 确保
pnpm build本地成功 - 检查 npm 令牌: 验证 npm 认证在 CI 中配置
- 检查版本格式: 确保版本遵循 semver 格式
- CI 日志: 检查 GitHub 动作日志中的特定错误消息
发布后导入出错
如果消费者报告进口出错:
- 验证出口: 检查
package.json导出符合实际文件 - 运行测试: 确保
pnpm test:run通过 - 检查构建输出: 校验
dist/包含预期文件 - 本地测试: 使用
npm link在发布前测试本地软件包