SuperAPI AI 工具集

dependencies

编程与开发

查看项目

更新于 10-30 18:19

技能介绍

用途:该技能面向 Docusaurus monorepo 的依赖维护,在编辑任何 package.json 依赖字段、执行 pnpm add/pnpm remove 等操作前使用,用于新增、移除或升级 npm 依赖。

主要能力与规则:

  1. 依赖声明集中在 pnpm-workspace.yaml 的 pnpm catalogs 中,包使用 catalog 协议引用,而不是直接写版本范围。默认 catalog 用于至少被一个包在运行时使用的依赖(dependencies、optionalDependencies 或 peerDependencies);catalog:dev 用于仅作为 devDependencies 使用的依赖。
  2. 使用 pnpm 命令增删依赖:pnpm add 仅接受 catalog 版本(catalogMode: strict),并把新依赖加入默认 catalog,仅开发用途的依赖需移到 dev catalog;pnpm remove 会清理不再使用的 catalog 条目(catalogPrune: true),而手动修改 package.json 不会触发清理。一旦某个包在运行时使用某 dev catalog 条目,应将其移到默认 catalog。
  3. 锁文件:任何锁文件变更后需运行 pnpm dedupe,若 pnpm-lock.yaml 未去重,CI 的 pnpm lint:deps 会失败。
  4. 站点模板依赖位于 packages/create-docusaurus/templates/,其版本必须与 catalogs 一致;examples/ 由 CLI 生成,不应编辑。
  5. 保留显式版本的例外:复制到用户站点的站点模板、pnpm overrides,以及有意与 catalog 范围不同的 peer 依赖(参见 .syncpackrc.ts 中忽略的版本组),后两者版本均需与 catalogs 匹配。
  6. 两项检查:pnpm lint:syncpack 要求依赖使用 catalog;pnpm lint:catalogs(admin/scripts/lintCatalogs.js)校验 catalog 条目被使用且位于正确的 catalog、模板与 overrides 与 catalogs 匹配、依赖组成员使用相同版本。
  7. 依赖组:部分包必须始终保持同一版本,这些组在 .github/dependabot.yml 中声明,Dependabot 会在单个 PR 中原子升级它们,避免产生中间态破坏性 PR;若组的 catalog 版本不一致,pnpm lint:catalogs 会失败。加入依赖组的情形包括:某包固定另一包的确切版本(如 @svgr/webpack 固定 @svgr/core 与 @svgr/plugin-*);某包对另一包有完全相同版本的 peer 依赖(如 @types/react-dom 与 @types/react);包在运行时校验版本一致(react 与 react-dom);混用版本会导致单例包重复(react-router 与 react-router-dom);包按锁定节奏发布且混版本会破坏类型检查(typescript-eslint)。
  8. 新增依赖时需检查是否属于某个依赖组:若已有组匹配(如 @svgr/* 匹配 @svgr/plugin-jsx)则无需处理;否则加入匹配的组或新建组,并遵循现有组格式,每个包家族一组并附注释说明必须同步的原因。当 Dependabot PR 因相关包未同步升级而无法通过 CI 时,也应按同样方式处理。

使用方式:按上述规则在修改依赖前使用 pnpm 命令操作 catalog,变更锁文件后运行 pnpm dedupe,并运行 pnpm lint:syncpack 与 pnpm lint:catalogs 进行校验。

适用场景:Docusaurus monorepo 的依赖新增、移除、升级,以及处理 Dependabot 依赖升级 PR。

限制:资料未提供该技能作为 AI 技能的具体调用方式、安装方式或价格等信息。