syncpack-configuration

Syncpack Configuration

Syncpack is a tool for managing consistent dependency versions across JavaScript/TypeScript monorepos. This skill covers configuration best practices.

Configuration File Locations

Syncpack searches for configuration in these locations (in order):

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

Basic Configuration

// syncpack.config.js
export default {
  // Glob patterns to find package.json files
  source: [
    'package.json',
    'packages/*/package.json',
    'apps/*/package.json',
  ],
};

Workspace Detection

Syncpack automatically detects workspaces:

• npm/Yarn: Reads workspaces from ./package.json
• pnpm: Reads packages from ./pnpm-workspace.yaml
• Lerna: Reads packages from ./lerna.json

Override with explicit source patterns when needed.

Dependency Types

Control which dependency types to check:

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

Semver Groups

Define rules for semver range consistency:

export default {
  semverGroups: [
    {
      // Require exact versions for React
      dependencies: ['react', 'react-dom'],
      range: '',  // exact version
    },
    {
      // Allow caret ranges for dev tools
      dependencyTypes: ['dev'],
      range: '^',
    },
  ],
};

Range Options

Range	Example	Meaning
''	1.2.3	Exact version
^	^1.2.3	Compatible with
~	~1.2.3	Approximately equivalent
>=	>=1.2.3	Greater than or equal
*	*	Any version

Version Groups

Partition dependencies into groups with separate version policies:

export default {
  versionGroups: [
    {
      // Pin specific dependencies
      dependencies: ['typescript'],
      pinVersion: '5.3.3',
    },
    {
      // Ban certain packages
      dependencies: ['moment'],
      isBanned: true,
    },
    {
      // Use workspace version as source of truth
      dependencies: ['@myorg/*'],
      preferVersion: 'highestSemver',
    },
  ],
};

Formatting Options

Control package.json formatting:

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

Common Patterns

Single Version Policy

Enforce one version per dependency across all packages:

export default {
  versionGroups: [
    {
      label: 'Use highest version everywhere',
      preferVersion: 'highestSemver',
    },
  ],
};

Allow Development Exceptions

export default {
  versionGroups: [
    {
      label: 'Ignore dev dependencies',
      dependencyTypes: ['dev'],
      isIgnored: true,
    },
    {
      label: 'Consistent versions for production',
      dependencyTypes: ['prod', 'peer'],
      preferVersion: 'highestSemver',
    },
  ],
};

Scoped Package Source of Truth

export default {
  versionGroups: [
    {
      label: 'Internal packages use local version',
      dependencies: ['@myorg/**'],
      dependencyTypes: ['local'],
      preferVersion: 'local',
    },
  ],
};

Best Practices

1. Start with defaults - Syncpack works well without configuration
2. Add rules incrementally - Only add rules as you encounter issues
3. Document exceptions - Use label field to explain why rules exist
4. Commit config file - Keep version policy in version control
5. Run in CI - Use syncpack list-mismatches --fail-fast in CI pipelines