SuperAPI AI 工具集

web-tooling-component-library

编程与开发

查看项目

更新于 10-15 19:52

技能介绍

用途:把一组 React 组件从应用文件变成其他项目可安装的包。核心是五条必须明确声明、而非默认成立的边界契约:样式如何到达使用方、落在哪个级联层、"use client" 是否在构建后保留、对使用方 React 有何要求、暴露多少入口。它们在构建包自身的仓库里都能通过,却在别人项目里失败。

主要能力与要点:

  1. 样式交付。三选一:编译好的独立 .css(使用方导入一次,需在 sideEffects 中列出所有样式表,否则生产构建会摇掉,dev 不摇树所以只在发布后暴露);运行时注入 <style>(无需导入,但 SSR 会闪、严格 CSP 需 nonce、级联顺序随模块求值顺序变化);仅发布类名(零体积、自动套用其 token,但依赖使用方扫描你的发布路径且类名需静态可分析)。
  2. 级联层契约。库样式放进具名 @layer;未分层的样式无论特异性都胜过分层样式,因此使用方普通规则可自然覆盖,无需靠更高特异性或 !important。注意层内 !important 会反转优先级。
  3. "use client" 保留。指令须在文件首行、import 之前,标在真正需要客户端能力的叶子模块上,不要放在根 barrel。构建需每个源模块对应一个输出文件(如 preserveModules)方可保留下;剥离是静默的,故需校验 dist 首行并统计数量比对。
  4. 消费契约。react、react-dom 声明为 peerDependencies 并给出覆盖所支持大版本的区间(如 ^18.0.0 || ^19.0.0),用固定 devDependency 规定构建测试版本;npm 7 起 peer 会被安装,区间过窄会导致 ERESOLVE。带身份的东西(渲染器、context、注册表)用 peer,可重复的叶子工具用 dependencies。
  5. 入口粒度。区分服务端安全入口 "." 与 "./client",使边界由使用方 import 路径强制。若 "." 传递引入客户端叶子即为误标;barrel 含客户端叶子会让整库变为仅客户端。

适用:组件转包、选择样式交付方式、排查样式缺失/无法覆盖/重复 React/服务端组件崩溃、内部包按源码还是产物消费。不涵盖:exports 映射机制与工作区布局、版本发布流程、打包器整体配置、组件 API 设计。

限制:具体代码示例见其 examples/core.md 与 reference.md;各构建工具的指令保留配置各异,资料未逐一给出,需按所用工具核对。