ts-packaging 是一个面向 TypeScript 库发布场景的技能,目标是以正确的 exports map 发布到合适的注册表。资料明确指出,应用部署(因为它不是库)以及框架自有的构建流程不在该技能范围内,后者属于框架专家的技能。
主要用途与选型:资料建议,内部使用或面向 Bun/Deno/ESM-only 消费者时,采用纯 ESM;面向广泛公开、仍需服务 CommonJS 消费者的库,采用双 ESM/CJS。注册表对比中,JSR 仅支持 ESM、直接发布 TypeScript 源码,适合 Deno/Node/Bun 库和文档丰富的 API;npm 以 ESM(或双 ESM/CJS)发布构建后的 .js 与 .d.ts,适合最广的公开覆盖面及 CJS 消费者。
关键规则:exports 条件中 “types” 放最前、“default” 放最后,因为条件按对象顺序匹配;import 必须对应 ESM,require 必须对应 CJS,不可把 require 指向 ESM;每个模块一个子路径,说明符保持一致,并显式设置 “type”: “module”;发布前用 attw(arethetypeswrong)校验;公开版本从 CI 携带 id-token: write 发布以获得 provenance。
使用方式:资料要求在任何实现之前并行启动三个 Agent 调用,分别为 fuse-ai-pilot:explore-codebase(检查 package.json、构建输出、目标)、fuse-ai-pilot:research-expert(通过 Context7/Exa 核实最新的 JSR/npm/Node exports 文档)、mcp__context7__query-docs(检查条件顺序、attw 用法);实现之后运行 fuse-ai-pilot:sniper 做验证。另给出 ESM-pure 的 package.json exports 示例(type 为 module,exports 的 “.” 下 types 指向 ./dist/index.d.ts、default 指向 ./dist/index.js),以及发布前校验命令 npx @arethetypeswrong/cli --pack。
参考文档按需加载:写 exports 字段时看 references/exports-map.md;向 JSR 发布 TypeScript 源码看 references/jsr-publishing.md;发布到 npm(双/ESM)看 references/npm-publishing.md;检查类型解析看 references/validation.md。模板包括双 ESM/CJS 与 ESM-pure 的 package.json、多入口 exports 的 jsr.json、带 provenance 的 GitHub Actions 发布工作流。
适用场景与限制:适合需要规划注册表、exports map、条件导出、类型声明与发布校验的 TypeScript 库作者。资料未提供具体收费、价格、平台支持范围或实际效果数据,这些暂未提供;关于 JSR 的“慢类型”问题,资料建议通过显式返回类型、属性类型和常量类型来修复,并提醒不要习惯性使用 --allow-slow-types,以免降低文档与 npm 兼容性。