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' }, ], };