Syncpack Version Groups

Syncpack Version Groups

Version groups allow you to define sophisticated dependency version policies in your monorepo. This skill covers advanced patterns for version management.

Version Group Structure

export default {
  versionGroups: [
    {
      label: 'Description of this group',
      dependencies: ['package-name', '@scope/**'],
      dependencyTypes: ['prod', 'dev'],
      packages: ['apps/**'],
      specifierTypes: ['exact', 'range'],
      // Policy options (choose one)
      preferVersion: 'highestSemver',
      // pinVersion: '1.0.0',
      // isBanned: true,
      // isIgnored: true,
    },
  ],
};

Filter Options

dependencies

Match specific packages by name or glob:

dependencies: [
  'react',           // exact match
  'react-*',         // wildcard
  '@types/**',       // scoped packages
  '{react,vue}',     // either/or
]

dependencyTypes

Filter by where dependencies appear:

dependencyTypes: [
  'dev',           // devDependencies
  'local',         // workspace: protocol
  'overrides',     // npm overrides
  'peer',          // peerDependencies
  'pnpmOverrides', // pnpm.overrides
  'prod',          // dependencies
  'resolutions',   // yarn resolutions
]

packages

Filter by which package.json files:

packages: [
  'apps/**',      // all apps
  'packages/core', // specific package
  '!packages/legacy', // exclude pattern
]

specifierTypes

Filter by version specifier format:

specifierTypes: [
  'exact',        // 1.2.3
  'range',        // ^1.2.3, ~1.0.0, >=2.0.0
  'tag',          // latest, next, canary
  'url',          // https://, git://
  'file',         // file:../path
  'workspace',    // workspace:*
]

Version Policies

preferVersion

Choose which version wins when mismatches exist:

// Use the highest semver version found
preferVersion: 'highestSemver'

// Use the lowest semver version found
preferVersion: 'lowestSemver'

// Use whatever a specific package has
preferVersion: 'packages/core'

// Use local workspace version
preferVersion: 'local'

pinVersion

Force all matches to use a specific version:

{
  label: 'Pin TypeScript to LTS',
  dependencies: ['typescript'],
  pinVersion: '5.3.3',
}

isBanned

Prevent packages from being used:

{
  label: 'Ban deprecated packages',
  dependencies: ['moment', 'request'],
  isBanned: true,
}

isIgnored

Exclude from version checking:

{
  label: 'Ignore local packages',
  dependencyTypes: ['local'],
  isIgnored: true,
}

Common Patterns

Monorepo Single Version Policy

export default {
  versionGroups: [
    {
      label: 'Ignore local workspace packages',
      dependencyTypes: ['local'],
      isIgnored: true,
    },
    {
      label: 'Use highest version for everything else',
      preferVersion: 'highestSemver',
    },
  ],
};

Framework Pinning

export default {
  versionGroups: [
    {
      label: 'Pin React version across all packages',
      dependencies: ['react', 'react-dom', '@types/react', '@types/react-dom'],
      pinVersion: '18.2.0',
    },
  ],
};

Different Rules for Apps vs Libraries

export default {
  versionGroups: [
    {
      label: 'Apps can have any version',
      packages: ['apps/**'],
      isIgnored: true,
    },
    {
      label: 'Libraries must have consistent versions',
      packages: ['packages/**'],
      preferVersion: 'highestSemver',
    },
  ],
};

Ban Security Vulnerabilities

export default {
  versionGroups: [
    {
      label: 'Ban packages with known vulnerabilities',
      dependencies: [
        'lodash', // use lodash-es instead
        'moment', // use date-fns instead
        'request', // use axios/fetch instead
      ],
      isBanned: true,
    },
  ],
};

Peer Dependency Flexibility

export default {
  versionGroups: [
    {
      label: 'Allow peer dependency flexibility',
      dependencyTypes: ['peer'],
      isIgnored: true,
    },
    {
      label: 'Strict versions for prod/dev',
      dependencyTypes: ['prod', 'dev'],
      preferVersion: 'highestSemver',
    },
  ],
};

Scoped Package Ownership

export default {
  versionGroups: [
    {
      label: 'Core team owns @myorg/core',
      dependencies: ['@myorg/core'],
      preferVersion: 'packages/core',
    },
    {
      label: 'UI team owns @myorg/ui-*',
      dependencies: ['@myorg/ui-*'],
      preferVersion: 'packages/ui',
    },
  ],
};

CLI Commands for Version Groups

# List all version mismatches
npx syncpack list-mismatches

# Fix version mismatches
npx syncpack fix

# Only fix specific dependencies
npx syncpack fix --dependencies react

# Only fix specific dependency types
npx syncpack fix --dependency-types prod,peer

Debugging Version Groups

Use labels and run with verbose output:

npx syncpack list-mismatches --log-levels warn,error

Order Matters

Version groups are evaluated in order. First matching group wins:

export default {
  versionGroups: [
    // Specific rule first
    { dependencies: ['react'], pinVersion: '18.2.0' },
    // General rule second
    { preferVersion: 'highestSemver' },
  ],
};