Syncpack配置Skill syncpack-configuration

---

name: syncpack-configuration user-invocable: false description: 用于为monorepo设置或配置syncpack。涵盖配置文件、工作空间检测和依赖版本管理的自定义规则定义。 allowed-tools:

• Read
• Write
• Edit
• Bash
• Grep
• Glob

---

Syncpack 配置

Syncpack 是一个用于在JavaScript/TypeScript monorepos中管理一致依赖版本的工具。本技能涵盖配置最佳实践。

配置文件位置

Syncpack 在这些位置搜索配置（按顺序）：

1. syncpack.config.js / .cjs / .mjs / .ts
2. syncpack.config.json / .yaml / .yml
3. .syncpackrc / .syncpackrc.json / .syncpackrc.yaml / .syncpackrc.yml

基本配置

// syncpack.config.js
export default {
  // 用于查找package.json文件的Glob模式
  source: [
    'package.json',
    'packages/*/package.json',
    'apps/*/package.json',
  ],
};

工作空间检测

Syncpack 自动检测工作空间：

• npm/Yarn：从 ./package.json 读取 workspaces
• pnpm：从 ./pnpm-workspace.yaml 读取 packages
• Lerna：从 ./lerna.json 读取 packages

需要时可使用明确的 source 模式覆盖。

依赖类型

控制要检查的依赖类型：

export default {
  dependencyTypes: [
    'dev',           // devDependencies
    'local',         // workspace: 协议依赖
    'overrides',     // npm overrides / yarn resolutions
    'peer',          // peerDependencies
    'pnpmOverrides', // pnpm overrides
    'prod',          // dependencies
    'resolutions',   // yarn resolutions
  ],
};

Semver 分组

定义semver范围一致性规则：

export default {
  semverGroups: [
    {
      // 要求React使用精确版本
      dependencies: ['react', 'react-dom'],
      range: '',  // 精确版本
    },
    {
      // 允许开发工具使用脱字符范围
      dependencyTypes: ['dev'],
      range: '^',
    },
  ],
};

范围选项

范围	示例	含义
''	1.2.3	精确版本
^	^1.2.3	兼容版本
~	~1.2.3	近似等效版本
>=	>=1.2.3	大于或等于
*	*	任意版本

版本分组

将依赖分区为具有独立版本策略的组：

export default {
  versionGroups: [
    {
      // 固定特定依赖版本
      dependencies: ['typescript'],
      pinVersion: '5.3.3',
    },
    {
      // 禁止某些包
      dependencies: ['moment'],
      isBanned: true,
    },
    {
      // 使用工作空间版本作为源
      dependencies: ['@myorg/*'],
      preferVersion: 'highestSemver',
    },
  ],
};

格式化选项

控制package.json格式化：

export default {
  formatBugs: true,
  formatRepository: true,
  sortAz: [
    'contributors',
    'dependencies',
    'devDependencies',
    'keywords',
  ],
  sortFirst: [
    'name',
    'version',
    'description',
    'main',
  ],
};

常见模式

单一版本策略

强制所有包中每个依赖使用一个版本：

export default {
  versionGroups: [
    {
      label: '在所有地方使用最高版本',
      preferVersion: 'highestSemver',
    },
  ],
};

允许开发例外

export default {
  versionGroups: [
    {
      label: '忽略开发依赖',
      dependencyTypes: ['dev'],
      isIgnored: true,
    },
    {
      label: '生产依赖的一致版本',
      dependencyTypes: ['prod', 'peer'],
      preferVersion: 'highestSemver',
    },
  ],
};

作用域包的源版本

export default {
  versionGroups: [
    {
      label: '内部包使用本地版本',
      dependencies: ['@myorg/**'],
      dependencyTypes: ['local'],
      preferVersion: 'local',
    },
  ],
};

最佳实践

1. 从默认开始 - Syncpack 无需配置即可良好工作
2. 逐步添加规则 - 仅在遇到问题时添加规则
3. 记录例外 - 使用 label 字段解释规则存在原因
4. 提交配置文件 - 将版本策略保持在版本控制中
5. 在CI中运行 - 在CI管道中使用 syncpack list-mismatches --fail-fast