拆解Kumo构建系统ESM-only、极致Tree-Shaking与RSC兼容背后的三步流水线【免费下载链接】kumoCloudflares component library for building modern web applications.项目地址: https://gitcode.com/gh_mirrors/kumo5/kumoKumocloudflare/kumo是 Cloudflare 出品的开源 React 组件库为现代 Web 应用提供开箱即用的 UI 组件。它的构建系统并非一次打包完事而是一条精心设计的三步流水线先做代码生成与 CSS 构建再用双通道vp pack产出 ESM-only 且可极致 Tree-Shaking 的产物最后打包 CLI 并完成质量门禁。本文将带你逐步拆解这套流水线背后的工程取舍。一张图看懂三步流水线总览pnpm run build的实际执行链见 package.json 的build脚本是步骤命令职责第 1 步codegen:registrycss-build.ts生成组件注册表JSON/MD/Schema复制并编译 CSS第 2 步vp pack双通道打包 ESM JS 产物 独立生成.d.ts类型声明第 3 步build-cli.ts构建随包发布的kumoCLI 工具下面逐一拆解。第一步代码生成 CSS 双版本构建1️⃣ 组件注册表生成codegen:registry构建前先运行 scripts/component-registry/index.ts从 TypeScript 类型和文档站 demo 示例中自动提取每个组件的 props、variant 取值与示例产出component-registry.json等元数据。这份组件说明书会被打进 npm 包既供 CLI 查询npx kumo doc Button也方便 AI 工具理解组件用法——源码见 packages/kumo/ai/USAGE.md。2️⃣ CSS 双版本策略scripts/css-build.ts 处理样式时会产出两套 CSS对应两种用户群体产物面向用户说明kumo.cssTailwind v4 用户保留theme令牌由项目侧的 Tailwind 统一编译kumo-standalone.css非 Tailwind 用户通过 Tailwind CLI 离线编译并压缩成完整 CSS这样无论你是否使用 Tailwind都能零配置引入正确样式——构建期就把两种场景都照顾到了。第二步vp pack 双通道——ESM-only 与 Tree-Shaking 的核心packages/kumo/vite.config.ts 中定义了一个**两次构建two passes**的 pack 配置这是整个构建系统最精妙的部分。为什么 JS 与类型声明要分开打因为两者对依赖的期望正好相反JS 通道把base-ui/react、cnfast、floating-ui等普通依赖全部打包进产物alwaysBundle: /./只有 peer 依赖React、图标库等保持外部引用。好处是消费者拿到的每个入口都是自包含的解析快、版本无冲突。d.ts 通道emitDtsOnly: true所有裸模块导入保持外部让类型检查指向消费者自己安装的真实包类型。两次构建共用dist/输出目录靠customExports把 JS 入口与相邻的.d.ts文件自动配对见 vite.config.ts。ESM-only为什么只提供import条件package.json 声明type: moduleexports中只有import条件没有任何require/main回退。类型校验通道直接启用attwarethetypeswrong的esm-onlyprofilevite.config.ts以error级别把关确保发布产物对 ESM 消费者 100% 正确。更有说服力的是验收测试import-entries.mjs 会像一个纯 Node ESM 消费者那样遍历package.json中每一个导出入口并逐一import任何一个入口在 Node 里导入失败即判定构建不合格由 node-esm-import.test.ts 拉起子进程执行。放弃 CJS 意味着更简单的产物结构、更小的体积也天然规避了双格式下类型声明错位的经典坑。极致 Tree-Shaking 的四个设计支点机制位置效果sideEffects白名单package.json只标记*.css为有副作用其余模块可被安全摇树每组件独立入口vite.config.tscloudflare/kumo/components/button等数百个细粒度导出按需加载重量级模块隔离src/code/index.tsShiki 语法高亮拆为独立code入口注释写明 avoid bundle bloatvendor 分包策略vite.config.tsadvancedChunks将cnfast、floating-ui等聚合为共享 chunk多入口间只加载一次Primitives 层src/primitives/同样每个原子组件一个入口且入口列表是构建期动态扫描目录生成的getPrimitiveEntries()见 vite.config.ts升级 Base UI 后新增原语自动获得独立入口零手工维护。RSC 兼容use client 与 server 入口分离React Server Components 场景对构建产物极其挑剔Kumo 做了两处针对性处理重新注入use client指令vite.config.ts打包器会丢弃源码中的use client指令构建时用banner钩子给所有客户端 chunk重新加上头部指令唯独code/server入口不加——它在服务端运行。code/server独立入口src/code/server.tsx专门提供给 Next.js / Astro 等 SSR 框架做 Shiki 语法高亮。构建配置中 Shiki仅在该 server 入口保持外部引用防止它被连带打进带use client的客户端 chunk同时按需懒加载语言包以控制体积。配合 React 本身作为 peer 依赖不被打包Kumo 组件可以在 RSC 中安全跨端服务端渲染结构客户端挂载交互。第三步CLI 打包与发布质量门禁build链的最后一环tsx src/command-line/build-cli.ts构建随包发布的kumo命令bin/kumo.js支持ls、doc、add等子命令源码位于 src/command-line/。发布前还有两道门禁attwESM 类型正确性校验esm-only profileerror 级别publint校验exports、files、peer 依赖等元数据vite.config.ts另有 export-path-validation.test.ts 自动比对文件系统中实际存在的组件 ↔ package.json 导出 ↔ 构建入口三方一致新增组件漏配任一环节CI 会直接失败。这套构建系统对使用者的实际好处理解流水线后作为用户你只需记住三条最佳实践优先细粒度导入import { Button } from cloudflare/kumo/components/button比主入口导入更利于摇树样式二选一Tailwind 用户import cloudflare/kumo/styles否则用/styles/standaloneSSR 场景语法高亮走cloudflare/kumo/code/server勿在客户端 bundle 中引入ESM-only 让你告别 CJS 互操作问题双通道打包让体积与类型各得其所RSC 双入口让组件库无缝跨越服务端与浏览器——这三点正是 Kumo 构建流水线值得借鉴的设计精华。延伸阅读资料路径构建配置双通道 packpackages/kumo/vite.config.tsCSS 构建脚本packages/kumo/scripts/css-build.ts包元数据exports/sideEffectspackages/kumo/package.json注册表生成逻辑packages/kumo/scripts/component-registry/主题令牌 CSSpackages/kumo/src/styles/kumo.cssRSC 服务端高亮入口packages/kumo/src/code/server.tsxESM 导入验收测试packages/kumo/tests/imports/【免费下载链接】kumoCloudflares component library for building modern web applications.项目地址: https://gitcode.com/gh_mirrors/kumo5/kumo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
拆解Kumo构建系统ESM-only、极致Tree-Shaking与RSC兼容背后的三步流水线【免费下载链接】kumoCloudflares component library for building modern web applications.项目地址: https://gitcode.com/gh_mirrors/kumo5/kumoKumocloudflare/kumo是 Cloudflare 出品的开源 React 组件库为现代 Web 应用提供开箱即用的 UI 组件。它的构建系统并非一次打包完事而是一条精心设计的三步流水线先做代码生成与 CSS 构建再用双通道vp pack产出 ESM-only 且可极致 Tree-Shaking 的产物最后打包 CLI 并完成质量门禁。本文将带你逐步拆解这套流水线背后的工程取舍。一张图看懂三步流水线总览pnpm run build的实际执行链见 package.json 的build脚本是步骤命令职责第 1 步codegen:registrycss-build.ts生成组件注册表JSON/MD/Schema复制并编译 CSS第 2 步vp pack双通道打包 ESM JS 产物 独立生成.d.ts类型声明第 3 步build-cli.ts构建随包发布的kumoCLI 工具下面逐一拆解。第一步代码生成 CSS 双版本构建1️⃣ 组件注册表生成codegen:registry构建前先运行 scripts/component-registry/index.ts从 TypeScript 类型和文档站 demo 示例中自动提取每个组件的 props、variant 取值与示例产出component-registry.json等元数据。这份组件说明书会被打进 npm 包既供 CLI 查询npx kumo doc Button也方便 AI 工具理解组件用法——源码见 packages/kumo/ai/USAGE.md。2️⃣ CSS 双版本策略scripts/css-build.ts 处理样式时会产出两套 CSS对应两种用户群体产物面向用户说明kumo.cssTailwind v4 用户保留theme令牌由项目侧的 Tailwind 统一编译kumo-standalone.css非 Tailwind 用户通过 Tailwind CLI 离线编译并压缩成完整 CSS这样无论你是否使用 Tailwind都能零配置引入正确样式——构建期就把两种场景都照顾到了。第二步vp pack 双通道——ESM-only 与 Tree-Shaking 的核心packages/kumo/vite.config.ts 中定义了一个**两次构建two passes**的 pack 配置这是整个构建系统最精妙的部分。为什么 JS 与类型声明要分开打因为两者对依赖的期望正好相反JS 通道把base-ui/react、cnfast、floating-ui等普通依赖全部打包进产物alwaysBundle: /./只有 peer 依赖React、图标库等保持外部引用。好处是消费者拿到的每个入口都是自包含的解析快、版本无冲突。d.ts 通道emitDtsOnly: true所有裸模块导入保持外部让类型检查指向消费者自己安装的真实包类型。两次构建共用dist/输出目录靠customExports把 JS 入口与相邻的.d.ts文件自动配对见 vite.config.ts。ESM-only为什么只提供import条件package.json 声明type: moduleexports中只有import条件没有任何require/main回退。类型校验通道直接启用attwarethetypeswrong的esm-onlyprofilevite.config.ts以error级别把关确保发布产物对 ESM 消费者 100% 正确。更有说服力的是验收测试import-entries.mjs 会像一个纯 Node ESM 消费者那样遍历package.json中每一个导出入口并逐一import任何一个入口在 Node 里导入失败即判定构建不合格由 node-esm-import.test.ts 拉起子进程执行。放弃 CJS 意味着更简单的产物结构、更小的体积也天然规避了双格式下类型声明错位的经典坑。极致 Tree-Shaking 的四个设计支点机制位置效果sideEffects白名单package.json只标记*.css为有副作用其余模块可被安全摇树每组件独立入口vite.config.tscloudflare/kumo/components/button等数百个细粒度导出按需加载重量级模块隔离src/code/index.tsShiki 语法高亮拆为独立code入口注释写明 avoid bundle bloatvendor 分包策略vite.config.tsadvancedChunks将cnfast、floating-ui等聚合为共享 chunk多入口间只加载一次Primitives 层src/primitives/同样每个原子组件一个入口且入口列表是构建期动态扫描目录生成的getPrimitiveEntries()见 vite.config.ts升级 Base UI 后新增原语自动获得独立入口零手工维护。RSC 兼容use client 与 server 入口分离React Server Components 场景对构建产物极其挑剔Kumo 做了两处针对性处理重新注入use client指令vite.config.ts打包器会丢弃源码中的use client指令构建时用banner钩子给所有客户端 chunk重新加上头部指令唯独code/server入口不加——它在服务端运行。code/server独立入口src/code/server.tsx专门提供给 Next.js / Astro 等 SSR 框架做 Shiki 语法高亮。构建配置中 Shiki仅在该 server 入口保持外部引用防止它被连带打进带use client的客户端 chunk同时按需懒加载语言包以控制体积。配合 React 本身作为 peer 依赖不被打包Kumo 组件可以在 RSC 中安全跨端服务端渲染结构客户端挂载交互。第三步CLI 打包与发布质量门禁build链的最后一环tsx src/command-line/build-cli.ts构建随包发布的kumo命令bin/kumo.js支持ls、doc、add等子命令源码位于 src/command-line/。发布前还有两道门禁attwESM 类型正确性校验esm-only profileerror 级别publint校验exports、files、peer 依赖等元数据vite.config.ts另有 export-path-validation.test.ts 自动比对文件系统中实际存在的组件 ↔ package.json 导出 ↔ 构建入口三方一致新增组件漏配任一环节CI 会直接失败。这套构建系统对使用者的实际好处理解流水线后作为用户你只需记住三条最佳实践优先细粒度导入import { Button } from cloudflare/kumo/components/button比主入口导入更利于摇树样式二选一Tailwind 用户import cloudflare/kumo/styles否则用/styles/standaloneSSR 场景语法高亮走cloudflare/kumo/code/server勿在客户端 bundle 中引入ESM-only 让你告别 CJS 互操作问题双通道打包让体积与类型各得其所RSC 双入口让组件库无缝跨越服务端与浏览器——这三点正是 Kumo 构建流水线值得借鉴的设计精华。延伸阅读资料路径构建配置双通道 packpackages/kumo/vite.config.tsCSS 构建脚本packages/kumo/scripts/css-build.ts包元数据exports/sideEffectspackages/kumo/package.json注册表生成逻辑packages/kumo/scripts/component-registry/主题令牌 CSSpackages/kumo/src/styles/kumo.cssRSC 服务端高亮入口packages/kumo/src/code/server.tsxESM 导入验收测试packages/kumo/tests/imports/【免费下载链接】kumoCloudflares component library for building modern web applications.项目地址: https://gitcode.com/gh_mirrors/kumo5/kumo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
