Skip to content
Syncpack
This documentation is for v14 and up, the docs for v13 are archived.

Same Range

Checks that every instance of a dependency uses a semver range that overlaps with every other instance in the group. Ranges don't need to be identical, they just need to share at least one version in common (ie. they intersect).

This is the loosest version group policy. It does not enforce identical versions; the default Highest Semver group does that. It does not enforce same minor versions; use sameMinor for that.

When to use this

  • Peer dependencies where different packages legitimately need different ranges, as long as a compatible version can be resolved
  • Typed dependencies (foo and @types/foo) that may move on different release cadences but must coexist

Examples

Overlapping ranges, at least one version satisfies both:

  • >=1.0.0 and <=2.0.0 ✅ (versions 1.0.0 to 2.0.0 satisfy both)
  • >=1.0.0 and ^1.2.3 ✅ (versions 1.2.3 to 1.x.x satisfy both)
  • ^1.0.0 and ~1.4.2 ✅ (versions 1.4.2 to 1.4.x satisfy both)

Non-overlapping ranges, no version exists in both:

  • >=1.0.0 and <1.0.0 ✗
  • ~1.0.0 and 1.4.2 ✗ (~1.0.0 covers 1.0.x, the exact version 1.4.2 is outside it)

Mismatches in a Same Range group are unfixable. Syncpack cannot auto-fix them because it doesn't know which range should change. You'll need to resolve these manually.

Configuration

policy Required

Choose the "sameRange" policy to apply this behaviour to a Version Group.

.syncpackrc.json
{
  "versionGroups": [
    {
      "dependencies": ["eslint"],
      "policy": "sameRange"
    }
  ]
}

dependencies Optional

  • An array of names of dependencies you've installed or otherwise reference in your package.json files.
  • If omitted, the default behaviour is to match every dependency.
  • The strings can be any combination of exact matches or glob patterns:
Examples of valid values
// match any dependency
dependencies: ["**"]


// match all dependencies with a certain scope
dependencies: ["@aws-sdk/**"]


// match specific dependencies by name
dependencies: ["react", "react-dom"]
Where this pattern is matched against
{
  "name": "HERE",
  "dependencies": { "HERE": "0.0.0" },
  "devDependencies": { "HERE": "0.0.0" },
  "overrides": { "HERE": "0.0.0" },
  "peerDependencies": { "HERE": "0.0.0" },
  "pnpm": { "overrides": { "HERE": "0.0.0" } },
  "resolutions": { "HERE": "0.0.0" }
}

dependencyTypes Optional

A "dependency type" refers to the path/location/nested property of package.json files where dependencies can be found.

  • When set, only dependencies present in the named locations will be assigned to this group.
  • If omitted, the default behaviour is to match dependencies everywhere they are found.
  • Negated types are also supported, so a value of ["!dev", "!prod"] would assign everything except dependencies and devDependencies to this group.
  • Auto-generated catalog dep types (pnpmCatalog, pnpmCatalog:<name>, bunCatalog, bunCatalog:<name>) are valid values in projects using pnpm or Bun catalogs.

specifierTypes Optional

  • When set, only dependencies whose version specifier matches the given specifier types will be assigned to this group.
  • If omitted, the default behaviour is to match all dependencies.
  • Negated types are also supported, so a value of ["!latest", "!file"] would assign everything except specifiers of the format * and file:path/to/package.tgz to this group.

label Optional

  • A short name or description displayed as a header in syncpack's output.
  • If a label is not set then eg. "Version Group 3" will be used instead.

packages Optional

  • An array of strings which should match the name properties of your package.json files.
  • If omitted, the default behaviour is to match every package.
  • Negated types are also supported, so a value of ["!my-client", "!my-server"] would assign everything except the packages my-client and my-server to this group.
  • The strings can be any combination of exact matches or glob patterns:
Examples of valid values
// ✅ match any package name
packages: ["**"]


// ✅ match any package name with this scope
packages: ["@my-repo/**"]


// ✅ match specific packages by name
packages: ["my-server", "my-client"]


// ✅ match all packages except negated ones
packages: ["!my-server", "!@my-repo/**]


// ❌ no mixing of specific and negated packages
packages: ["my-client", "!@my-repo/**"]


// ❌ not file system paths, name properties of package.json files
packages: ["packages/my-client"]


// ❌ not file system globs, name properties of package.json files
packages: ["packages/**"]
Where this pattern is matched against
{
  "name": "HERE",
  "version": "1.0.2"
}

severity Optional

Override the default severity of any status code this group can produce.

.syncpackrc.json
{
  "versionGroups": [
    {
      "dependencies": ["eslint"],
      "policy": "sameRange",
      "severity": {
        "SemverRangeMismatch": "warn"
      }
    }
  ]
}

Permitted keys:

SameRangeMismatch is unfixable. It is always reported as an error and cannot be tuned via severity.

Status Codes

These are all the issues that a Same Range Version Group can find:

Valid

Fixable

Unfixable