Syncpack

Syncpack リファレンス

Syncpack（syncpack.dev）の全ドキュメントを網羅したスキル。 ユーザーのタスクに応じて適切な README.md を読み、そこから個別ファイルへ辿ること。

ディレクトリ構成

skills/syncpack/
  SKILL.md
  references/
    guide/
      README.md
      getting-started.md
      migrate-v14.md
      migrate-v15.md
      peer-dependencies.md
      whats-new.md
    commands/
      README.md
      fix.md
      format.md
      json.md
      lint.md
      list.md
      update.md
    version-groups/
      README.md
      banned.md
      catalog.md
      highest-semver.md
      ignored.md
      lowest-semver.md
      pinned.md
      range-only.md
      same-minor.md
      same-range.md
      snapped-to.md
    semver-groups/
      README.md
      ignored.md
      with-range.md
    update-groups/
      README.md
      ignored.md
      targeted.md
    config/
      README.md
      syncpackrc.md
      custom-types.md
      dependency-groups.md
      format-bugs.md
      format-repository.md
      indent.md
      max-concurrent-requests.md
      minimum-release-age.md
      semver-groups.md
      severity.md
      sort-az.md
      sort-exports.md
      sort-first.md
      sort-packages.md
      source.md
      source-mode.md
      strict.md
      update-groups.md
    reference/
      README.md
      dependency-types.md
      glossary.md
      specifier-types.md
      status.md
  samples/
    README.md
    basic-lint-and-fix.md
    ban-dependency.md
    ci-workflow.md
    custom-types.md
    format-package-json.md
    minimal-config.md
    pin-version.md
    semver-range-policy.md
    snap-to-source.md
    update-dependencies.md
    workspace-protocol.md
  scripts/
    README.md
    cli.md
    install.md

探索手順

タスクからカテゴリを引き、カテゴリの README.md で目的のページを特定する:

1. 下記マッピング表でタスクに対応するカテゴリを探す 2. そのカテゴリの references/{category}/README.md を参照して目的のページを特定する 3. 該当ページの .md を Read して詳細を確認する

タスク → カテゴリ マッピング

fix

Source: https://syncpack.dev/command/fix/

Autofix dependency version mismatches across your monorepo to match configured rules. Addresses issues identified by lint but does not handle formatting (use format for that).

Usage

syncpack fix [options]

Options

Examples

# Preview changes without writing
syncpack fix --dry-run

# Fix production and dev dependencies only
syncpack fix --dependency-types prod,dev

# Fix exact versions only (e.g. "1.2.3", not ranges)
syncpack fix --specifier-types exact

# Fix a specific dependency across all packages
syncpack fix --dependencies react

# Fix scoped packages using a wildcard
syncpack fix --dependencies '@types/**'

# Output machine-readable NDJSON
syncpack fix --reporter json

Notes

• Use --dry-run to preview what would change before committing
• Quote special characters (!, {, }, *) to prevent shell interpretation
• Config file discovery order: --config flag → config file source setting → workspace definitions (npm/Yarn/pnpm/Lerna) → defaults (package.json and packages/*/package.json)

Related

• lint
• format

format

Source: https://syncpack.dev/command/format/

Sort package.json fields into a consistent order and alphabetize nested fields across all packages in a monorepo. Does not alter version numbers.

Usage

syncpack format [options]

Options

Examples

# Format all packages
syncpack format

# Check formatting without writing
syncpack format --check

# Check a single package only
syncpack format --check --source 'packages/pingu/package.json'

# Preview changes without writing
syncpack format --dry-run

# Output machine-readable NDJSON
syncpack format --reporter json

Notes

• --check is for CI validation; --dry-run is for local preview
• JSON reporter outputs one line per issue (e.g. status PropertyIsNotSortedAz)
• Quote special characters in glob patterns to prevent shell interpretation
• Source discovery order: --source flag → config file → workspace definitions → defaults

Related

• lint
• fix

json

Source: https://syncpack.dev/command/json/

Export all dependency instance data from a monorepo as newline-delimited JSON (one object per instance). Each line contains version, location, and status information. Designed for piping into jq or other tooling.

Note: fix and format also support --reporter json for machine-readable output.

Usage

syncpack json [options]

Options

Examples

# All dependencies as NDJSON
syncpack json

# Filter by scoped package name pattern
syncpack json --dependencies '@aws-sdk/**'

# Count dependencies by type using jq
syncpack json | jq -r '.dependencyType' | sort | uniq -c

Output

Each line is a JsonOutput object containing:

• Dependency name and version
• Location (which package.json file and field)
• Status (mismatch, valid, ignored, etc.)

Related

• list
• lint

lint

Source: https://syncpack.dev/command/lint/

Check for dependency version mismatches across a monorepo. Reports issues without modifying files. Exits with code 1 if issues are found. Use fix to resolve version mismatches; use format --check for formatting validation.

Usage

syncpack lint [options]

Options

Examples

# Check prod and dev dependencies
syncpack lint --dependency-types prod,dev

# Check a specific dependency
syncpack lint --dependencies react

# Check scoped packages with wildcard
syncpack lint --dependencies '@types/**'

# Exclude peer dependencies
syncpack lint --dependency-types '!peer'

# Show instance-level detail for exact versions only
syncpack lint --show instances --specifier-types exact

# Sort issues by frequency
syncpack lint --sort count

Notes

• Read-only: never modifies files
• Exit code 0 = no issues; exit code 1 = issues found
• Quote special characters (!, {, }, *) to prevent shell interpretation
• Config discovery order: --source flag → config file → workspace definitions (npm/Yarn/pnpm/Lerna) → defaults

Related

• fix
• format
• list

list

Source: https://syncpack.dev/command/list/

Display all dependencies across a monorepo with their versions and locations. Shows which dependencies have mismatches, are ignored, or comply with configured rules. Useful for exploration before running lint or fix.

Usage

syncpack list [options]

Options

Examples

# Sort by most common dependency
syncpack list --sort count

# Show per-package instance detail
syncpack list --show instances

# Peer dependencies only
syncpack list --dependency-types peer

# Scoped package filter
syncpack list --dependencies '@types/**'

# Combine filters
syncpack list --specifier-types exact --show instances --dependency-types peer

Related

• lint
• fix
• json

Commands

syncpack CLI コマンド一覧。

update

Source: https://syncpack.dev/command/update/

Update dependencies in your monorepo to newer versions from the npm registry. Fetches latest published versions and modifies package.json files. Differs from fix, which synchronizes versions across packages without consulting npm.

Usage

syncpack update [options]

Options

Update Strategies (--target)

Examples

# Accept any available update
syncpack update --target latest

# Minor updates only
syncpack update --target minor

# Patch updates only
syncpack update --target patch

# Check without modifying
syncpack update --check

# Check a single package
syncpack update --check --source 'packages/pingu/package.json'

# Update prod and dev only
syncpack update --dependency-types dev,prod

# Update a specific dependency
syncpack update --dependencies react

# Wildcard match
syncpack update --dependencies '**react**'

# Scoped packages
syncpack update --dependencies '@aws-sdk/**'

Notes

• Requires network access to the npm registry
• Versions newer than minimumReleaseAge (default: 1440 minutes) are excluded to reduce supply chain attack risk
• Registry responses are cached locally for 30 minutes; use --no-cache to bypass
• Per-dependency update control is available via updateGroups in the config file; the stricter of CLI --target and group target wins
• Quote special characters in glob patterns to prevent shell interpretation
• Config discovery order: --config flag → config file → workspace definitions → defaults

Related

• fix
• lint

customTypes

Source: https://syncpack.dev/config/custom-types/

Define custom package.json properties to manage beyond standard dependency types such as prod, dev, and peer.

Property

Strategies

Default Configuration

The built-in types are defined internally as:

{
  "customTypes": {
    "dev": {
      "strategy": "versionsByName",
      "path": "devDependencies"
    },
    "prod": {
      "strategy": "versionsByName",
      "path": "dependencies"
    }
  }
}

Example: engines and packageManager

{
  "customTypes": {
    "engines": {
      "strategy": "versionsByName",
      "path": "engines"
    },
    "packageManager": {
      "strategy": "name@version",
      "path": "packageManager"
    }
  }
}

Notes

• Custom types can be referenced by name in the --dependency-types CLI option
• Custom types work with dependencyTypes in Version Groups, Semver Groups, and Dependency Groups
• Nested paths use dot notation (e.g., "some.nested.property")

dependencyGroups

Source: https://syncpack.dev/config/dependency-groups/

Group multiple dependencies to be treated as a single entity for version management. Useful for package families such as @aws-sdk/** that should always share the same version.

Properties

Dependency Pattern Examples

Example

{
  "dependencyGroups": [
    {
      "dependencies": ["@aws-sdk/**"],
      "aliasName": "aws-sdk-dependencies"
    }
  ]
}

Notes

• Cannot mix specific and negated patterns in the same dependencies or packages array
• packages values reference the name field in package.json, not file paths
• The group alias is used in versionGroups and semverGroups configuration to apply rules to the entire group

formatBugs

Source: https://syncpack.dev/config/format-bugs/

When using the format command, enables formatting of the bugs field of package.json into a shorthand format.

Property

Configuration

{
  "formatBugs": false
}

Notes

• Applies only to the format command
• No corresponding CLI option is available; must be set in the config file

formatRepository

Source: https://syncpack.dev/config/format-repository/

When using the format command, enables formatting of the repository field of package.json into a shorthand format.

Property

Configuration

{
  "formatRepository": false
}

Notes

• Applies only to the format command
• No corresponding CLI option is available; must be set in the config file

indent

Source: https://syncpack.dev/config/indent/

When syncpack writes to package.json files, determines which characters to indent the JSON with.

Property

Configuration

{
  "indent": "  "
}

Common Values

Notes

• Controls whitespace applied during all syncpack write operations
• Set this to match your project's existing formatting preferences

maxConcurrentRequests

Source: https://syncpack.dev/config/max-concurrent-requests/

The maximum number of HTTP requests to the npm registry to keep in-flight at any given time when running the update command.

Property

Configuration

{
  "maxConcurrentRequests": 12
}

Notes

• Only used by the update command
• Lower values reduce network/registry load at the cost of slower update checks
• Higher values speed up update checks but increase concurrent connections

minimumReleaseAge

Source: https://syncpack.dev/config/minimum-release-age/

Minimum age in minutes a published package version must reach before syncpack considers it for updates. Reduces supply chain attack risk by filtering out very recently published versions.

Property

Usage

{
  "minimumReleaseAge": 10080
}

Notes

• Applies to the update command only
• Default is 1440 minutes (24 hours); "Most malicious releases are detected and unpublished within an hour"
• When omitted from .syncpackrc, reads from pnpm-workspace.yaml if present
• Setting to 0 disables the filter entirely
• Added in v15.0.0

Related

• update command
• updateGroups

config

semverGroups

Source: https://syncpack.dev/semver-groups/

Allow some dependencies to have different semver range rules to the rest of your monorepo. Each dependency can only belong to one semver group — the first rule that matches a given dependency and package will apply.

Property

Common Matching Properties

All semver group variants share these optional matching properties:

Variants

ignored

Exclude specific dependencies from semver range validation and enforcement.

{
  "semverGroups": [
    {
      "packages": ["oops-moment", "workaround"],
      "isIgnored": true
    }
  ]
}

with-range

Ensure all dependencies within this group use the specified semver range format.

{
  "semverGroups": [
    {
      "dependencies": ["@foo/**"],
      "range": "~"
    }
  ]
}

Full Example

{
  "semverGroups": [
    {
      "dependencyTypes": ["prod", "resolutions", "overrides", "pnpmOverrides", "local"],
      "range": ""
    },
    {
      "dependencyTypes": ["dev"],
      "range": "~"
    },
    {
      "dependencyTypes": ["peer"],
      "range": "^"
    }
  ]
}

Notes

• Groups are evaluated in order; the first matching group wins
• A dependency belongs to exactly one semver group
• Omitting all matching properties causes the group to match everything (useful as a catch-all last entry)

severity

Source: https://syncpack.dev/config/severity/

Override the default treatment for status codes syncpack assigns to dependencies. Configurable per version group via the optional severity map.

Property

Severity Values

Default Behaviors

strict: true escalates unspecified Suspect statuses from "warn" to "error". Explicit severity mappings always take precedence.

Usage

{
  "versionGroups": [
    {
      "label": "Treat banned dependencies as errors",
      "dependencies": ["lodash"],
      "isBanned": true,
      "severity": {
        "IsBanned": "error"
      }
    }
  ]
}

Non-Configurable Status Codes

Notes

• Added in v15.2.0
• strict: true and explicit severity maps can coexist; explicit maps take precedence

Related

• strict
• version-groups

sortAz

Source: https://syncpack.dev/config/sort-az/

When using the format command, sorts the specified package.json fields alphabetically. When the value is an Object, its keys are sorted; when it is an Array, its values are sorted.

Property

Default Value

{
  "sortAz": [
    "bin",
    "contributors",
    "dependencies",
    "devDependencies",
    "keywords",
    "peerDependencies",
    "resolutions",
    "scripts"
  ]
}

Notes

• Applies only to the format command
• No corresponding CLI option is available; must be set in the config file
• Add or remove field names to control which package.json fields are sorted

sortExports

Source: https://syncpack.dev/config/sort-exports/

When using the format command, orders the properties of the exports field in package.json according to the specified array. Aligns with Node.js documentation for conditional exports.

Property

Default Value

{
  "sortExports": [
    "types",
    "node-addons",
    "node",
    "browser",
    "module",
    "import",
    "require",
    "svelte",
    "development",
    "production",
    "script",
    "default"
  ]
}

Disable Sorting

{
  "sortExports": []
}

Notes

• Applies only to the format command
• No corresponding CLI option is available; must be set in the config file
• An empty array disables export sorting entirely
• The default order follows Node.js package export conventions

sortFirst

Source: https://syncpack.dev/config/sort-first/

When using the format command, determines which fields within package.json files should appear at the top, and in what order. Fields not listed here are sorted alphabetically after (controlled by sortPackages).

Property

Default Value

{
  "sortFirst": ["name", "description", "version", "author"]
}

Notes

• Applies only to the format command
• No corresponding CLI option is available; must be set in the config file
• Works together with sortPackages: sortFirst pins priority fields to the top, and sortPackages sorts the remaining fields alphabetically

Related

• ./sort-packages.md

sortPackages

Source: https://syncpack.dev/config/sort-packages/

When using the format command, enables sorting of root-level properties of package.json in alphabetical order.

Property

Configuration

{
  "sortPackages": true
}

Notes

• Applies only to the format command
• No corresponding CLI option is available; must be set in the config file
• Works together with sortFirst: fields listed in sortFirst are pinned to the top, then remaining fields are sorted alphabetically by sortPackages

Related

• ./sort-first.md

sourceMode

Source: https://syncpack.dev/config/source-mode/

Determines how custom source patterns interact with package files automatically discovered from your package manager's workspace configuration.

Property

Usage

{
  "sourceMode": "extend",
  "source": ["tools/scripts/package.json"]
}

Values

CLI Override

--source-mode <replace|extend> takes precedence over the configuration file setting.

Notes

• When using extend, discovered patterns appear first; custom patterns follow
• Added in v15.2.0

Related

• source
• update command

source

Source: https://syncpack.dev/config/source/

Glob patterns to discover which package.json files syncpack should manage. Useful for monorepos and distributed project structures.

Property

Resolution Priority

Syncpack resolves package.json files in the following order (highest to lowest priority):

1. --source CLI option 2. source configuration property 3. Workspace configurations (npm, Yarn, or pnpm workspaces) 4. Lerna configuration 5. Default patterns: "package.json" and "packages/*/package.json"

Example

{
  "source": ["./*/package.json", "./*/packages/*/package.json"]
}

Notes

• Supports any glob pattern valid for your file system
• Can target multiple repository structures simultaneously
• Syncpack does not require a monorepo setup; source can point to multiple separate repositories
• Placing a .syncpackrc.json with appropriate source patterns in a shared parent directory allows cross-repo dependency management

strict

Source: https://syncpack.dev/config/strict/

Controls whether syncpack exits with a non-zero error code when version mismatches are detected.

Property

Configuration

{
  "strict": false
}

Behavior

Notes

• Enable strict: true in CI/CD pipelines to enforce version consistency as a mandatory gate
• Prevents builds or deployments when dependency versions do not align across packages

.syncpackrc

Source: https://syncpack.dev/config/syncpackrc/

Configuration file for syncpack. Only properties you want to change from the defaults need to be specified.

Search Order

Syncpack searches for configuration in the following priority order:

1. .syncpackrc (no extension, JSON format) 2. .syncpackrc.json, .syncpackrc.yaml, .syncpackrc.yml, .syncpackrc.js, .syncpackrc.ts, .syncpackrc.mjs, .syncpackrc.cjs 3. syncpack.config.js, syncpack.config.ts, syncpack.config.mjs, syncpack.config.cjs 4. syncpack or config.syncpack property in package.json

To specify a custom location (requires a file extension):

syncpack list --config ./config/syncpack.json

Supported Formats

JSON (Recommended)

Preferred for fastest performance — no Node.js/TypeScript overhead.

{
  "$schema": "./node_modules/syncpack/schema.json",
  "indent": "    "
}

TypeScript

export default {
  indent: "    ",
} satisfies import("syncpack").RcFile;

JavaScript

// @ts-check
/** @type {import("syncpack").RcFile} */
const config = {
  indent: "    ",
};
module.exports = config;

Notes

• JSON format is recommended for performance (avoids TypeScript/Node.js compilation overhead)
• The $schema property enables IDE autocompletion when using JSON format
• Configuration values are merged with defaults; only overrides need to be specified

updateGroups

Source: https://syncpack.dev/update-groups/

Provide granular control over which registry updates qualify for the update command. Groups are evaluated sequentially through source order; the first matching group applies. Unmatched instances default to the CLI's --target value.

Property

Usage

{
  "updateGroups": [
    {
      "label": "Storybook — patch only",
      "dependencies": ["@storybook/**"],
      "target": "patch"
    },
    {
      "label": "Dev dependencies — minor only",
      "dependencyTypes": ["dev"],
      "target": "minor"
    },
    {
      "label": "Ignore peer dependencies",
      "dependencyTypes": ["peer"],
      "isIgnored": true
    }
  ]
}

Group Types

Target Strictness

The stricter of the CLI --target flag and a group's target wins. A group with target: "latest" cannot override --target patch passed on the CLI.

Notes

• Added in v15.1.1
• All filter properties (dependencies, dependencyTypes, packages, specifierTypes, label) are optional; omitted properties match all values

Related

• update command
• minimumReleaseAge
• update-groups/ignored
• update-groups/targeted

Getting Started

Source: https://syncpack.dev/

Overview

Syncpack is a CLI tool for maintaining consistent dependency versions across JavaScript monorepos. It can identify and resolve version conflicts, enforce semver range policies, locate outdated packages, pin versions, and standardize package.json formatting.

Used by: AWS, Cloudflare, DataDog, Electron, Microsoft, Vercel, and others.

Try Without Installing

Run from your monorepo root via npx:

npx syncpack list --dependency-types prod

Installation

npm install syncpack --save-dev

npm exec syncpack -- list

CLI Commands

All commands support -h (quick summary) and --help (detailed docs with examples).

Common Options

Examples

# List prod dependencies
syncpack list --dependency-types prod

# List only issues in prod + dev
syncpack lint --dependency-types prod,dev

# Fix everything
syncpack fix

# Fix only react
syncpack fix --dependencies react

# Check for outdated react upgrades
syncpack update --check --dependencies react

# Check for patch-level dev dependency updates
syncpack update --check --dependency-types dev --target patch

# Apply updates (omit --check)
syncpack update --dependencies react

# Glob patterns for filtering
syncpack list --dependencies '**eslint**'
syncpack list --dependencies '@types/**'

# Filter by specifier type
syncpack list --specifier-types exact

Configuration

Create .syncpackrc (JSON, YAML, JS, TS, MJS, CJS) in your repo root. Can also be defined as a syncpack property in package.json.

Custom config path requires an extension:

syncpack list --config ./config/syncpack.json

Minimal Config (production deps only)

Start narrow, expand gradually:

{
  "versionGroups": [
    {
      "label": "Sync all production dependencies",
      "dependencyTypes": ["prod"]
    },
    {
      "label": "Ignore everything else",
      "isIgnored": true
    }
  ]
}

Focus on Specific Packages

{
  "versionGroups": [
    {
      "label": "Sync react dependencies only",
      "dependencies": ["react", "react-dom"],
      "dependencyTypes": ["prod"]
    },
    {
      "label": "Ignore everything else",
      "isIgnored": true
    }
  ]
}

Enforce workspace:* for Internal Packages

{
  "versionGroups": [
    {
      "label": "Use `workspace:*` protocol for local packages",
      "dependencies": ["$LOCAL"],
      "dependencyTypes": ["dev", "prod"],
      "pinVersion": "workspace:*"
    },
    {
      "label": "Ignore everything else",
      "isIgnored": true
    }
  ]
}

Schema Support (TypeScript / JavaScript)

export default {
  indent: "    ",
} satisfies import("syncpack").RcFile;

/** @type {import("syncpack").RcFile} */
const config = { indent: "    " };
module.exports = config;

Notes

• After running fix or update, run your package manager (npm install, pnpm install, etc.) to refresh lockfiles.
• See Peer Dependencies for monorepos that use peer dependencies.
• See Version Groups and Semver Groups for advanced policies.

Related

• Migrate to v14
• Peer Dependencies

Migrate to v14

Source: https://syncpack.dev/guide/migrate-v14/

Overview

v14 consolidates commands, renames CLI options, and removes config properties in favor of more flexible alternatives. The core change is that semver range management and version mismatch checking are now inseparable.

Command Changes

Merged Commands

# v13
syncpack list-mismatches --types prod,dev
syncpack lint-semver-ranges

# v14
syncpack lint --dependency-types prod,dev

# v13
syncpack fix-mismatches
syncpack set-semver-ranges

# v14
syncpack fix

Formatting checks moved to:

syncpack format --check

Removed Command

prompt — the interactive prompt for issues that can't be auto-fixed — is not available in v14 and will be added at a later date.

CLI Option Changes

# v13
syncpack list-mismatches --filter "^@types\/.+"

# v14
syncpack lint --dependencies "@types/**"

Configuration Property Changes

Removed: dependencyTypes (top-level)

Use versionGroups instead, or use --dependency-types CLI flag for one-off filtering.

{
  "versionGroups": [
    {
      "label": "Ignore everything except prod, dev, peer",
      "dependencies": ["!prod", "!dev", "!peer"],
      "isIgnored": true
    }
  ]
}

Removed: specifierTypes (top-level)

Use versionGroups with a specifierTypes property, or use --specifier-types CLI flag.

Removed: lintFormatting

Formatting is now exclusively handled by syncpack format.

syncpack format --check

Removed: lintSemverRanges

Semver range checking is always enabled alongside version linting. The two are inseparable in v14 because changes to semver ranges affect which versions are considered valid.

Removed: lintVersions

Version linting is now always enabled and this option became redundant.

Legacy Version Migrations

Related

• Getting Started
• Peer Dependencies

Migrate to v15

Source: https://syncpack.dev/guide/migrate-v15/

Upgrade guide for Syncpack v15. The install step is unchanged.

npm install --save-dev syncpack

Breaking Change: pnpmOverrides

pnpmOverrides now reads from pnpm-workspace.yaml instead of package.json. This aligns with current pnpm conventions.

Legacy compatibility

If your overrides remain in package.json under pnpm.overrides, add a custom type to maintain compatibility:

{
  "customTypes": {
    "pnpmOverridesLegacy": {
      "strategy": "versionsByName",
      "path": "pnpm.overrides"
    }
  }
}

The standard pnpmOverrides type will continue to manage pnpm-workspace.yaml going forward.

New Features in v15

Related

• migrate-v14
• what's new
• catalog version group
• updateGroups config

Peer Dependencies

Source: https://syncpack.dev/guide/peer-dependencies/

Overview

Peer dependencies have fundamentally different version semantics from regular dependencies. Syncpack needs explicit configuration to understand when apparent mismatches are actually valid.

Regular vs Peer Dependency Ranges

Peer dependencies use wide ranges because the package is designed to work with as many consuming projects as possible.

The Problem

Syncpack compares versions literally. A peer dependency range and a concrete devDependency version will almost always look like a mismatch, even when they are compatible.

Example:

// ESLint plugin (peerDependencies)
{
  "peerDependencies": {
    "eslint": ">=6.0.0 <9.0.0"
  }
}

// Root package (devDependencies)
{
  "devDependencies": {
    "eslint": "8.53.0"
  }
}

Syncpack flags >=6.0.0 <9.0.0 vs 8.53.0 as a mismatch, even though 8.53.0 satisfies the peer range.

Solution

Use versionGroups in .syncpackrc to tell Syncpack how to handle peer dependency instances — typically by ignoring them or isolating them into a separate group with sameRange policy.

Option 1: Ignore All Peer Dependencies

{
  "versionGroups": [
    {
      "label": "Ignore peer dependencies",
      "dependencyTypes": ["peer"],
      "isIgnored": true
    }
  ]
}

Option 2: Use sameRange for Peer Dependencies

Checks that all semver ranges for a dependency overlap (i.e., there exists at least one version that satisfies all of them):

{
  "versionGroups": [
    {
      "label": "Peer dependencies use sameRange policy",
      "dependencyTypes": ["peer"],
      "policy": "sameRange"
    }
  ]
}

Option 3: Isolate Peer + Dev Together

Prevent peer dependency declarations from being compared against other dependency types:

{
  "versionGroups": [
    {
      "label": "Each package manages its own peer + dev versions",
      "dependencyTypes": ["peer", "dev"],
      "packages": ["@myrepo/eslint-plugin"],
      "isIgnored": true
    }
  ]
}

Notes

• The right approach depends on your monorepo's architecture. Consult Version Groups for all available policies.
• $LOCAL can be used in dependencies arrays to match internal workspace packages.
• Order versionGroups from most specific to most general — first match wins.

Related

• Getting Started
• Version Groups
• Semver Groups

guide

What's New

Source: https://syncpack.dev/guide/whats-new/

Summary of notable features added in recent Syncpack releases.

v15.3.0

Range Only Version Group (semverRangeOnly): Enforces consistent semver range prefixes (^, ~, or exact) across instances without syncing actual version numbers. See range-only.

Update Summary: The interactive update command now displays only the updates actually applied, rather than all candidates found.

v15.2.0

Severity Override: The severity map on version groups lets you disable autofixes for specific status codes, or escalate to errors. See severity.

sourceMode: New sourceMode: "extend" option appends custom source patterns to workspace-discovered patterns instead of replacing them. See sourceMode.

Non-package.json Support: The source option now accepts other JSON filenames when explicitly specified; improved glob and gitignore matching.

v15.1.1

Update Groups: Control how and whether monorepo sections receive npm updates, with options for patch/minor targeting and ignoring peer dependencies. See updateGroups.

Interactive Picker: The update command gains a keyboard-driven interface (--interactive): space toggles, a toggles all, enter confirms.

Registry Caching: npm registry responses cache locally for 30 minutes by default. Pass --no-cache to bypass.

v15.0.0

Catalog Protocol: Full support for pnpm and Bun catalogs with the catalog: protocol. See catalog version group.

Minimum Release Age: minimumReleaseAge (default: 1440 minutes) excludes recently-published versions for supply-chain security. See minimumReleaseAge.

Breaking Change: pnpmOverrides now reads from pnpm-workspace.yaml instead of package.json. See migrate-v15.

Related

• migrate-v15
• migrate-v14

Dependency Types

Source: https://syncpack.dev/dependency-types/

Dependency types refer to the various locations within package.json files where dependencies can be defined and managed by syncpack.

Default Dependency Types

Syncpack recognizes seven standard dependency type locations defined by npm, pnpm, and yarn:

Custom Types

Users can extend the default list by defining custom types in configuration to handle additional package.json sections such as:

• Engine versions (engines)
• Package manager versions (packageManager)
• Any other nested property in package.json

See the custom types guide for implementation details.

Command-Line Usage

Use --dependency-types to filter operations to specific types:

# Production dependencies only
syncpack lint --dependency-types prod

# Multiple types
syncpack lint --dependency-types prod,dev

# Exclude a type (prefix with !)
syncpack lint --dependency-types '!peer'

Configuration Usage

Dependency types serve as filters in three configuration contexts:

Related

• ./glossary.md
• ./specifier-types.md

Glossary

Source: https://syncpack.dev/glossary/

Key terms used throughout syncpack documentation.

Terms

Related

• ./dependency-types.md
• ./specifier-types.md
• ./status.md

reference

Specifier Types

Source: https://syncpack.dev/specifier-types/

Specifier types classify the different version specifier formats found in package.json files. They enable applying targeted rules to dependencies based on how their versions are specified.

All Specifier Types

Command-Line Usage

Use --specifier-types to filter operations to specific specifier types:

# Only exact versions
syncpack lint --specifier-types exact

# Exclude URL specifiers
syncpack lint --specifier-types '!url'

Configuration Usage

Specifier types can be used in Version Group configurations to apply rules based on version format. For example, you can target only range specifiers or exclude workspace-protocol entries from certain policies.

Related

• ./dependency-types.md
• ./glossary.md

Status

Source: https://syncpack.dev/status/

Syncpack assigns one status code to every dependency instance during monorepo analysis. Codes are organized into five categories. Applies to syncpack v14.

Valid (13 codes)

Dependencies that comply with configuration rules. No action required.

Fixable (12 codes)

Issues that can be automatically corrected by syncpack fix.

Unfixable (4 codes)

Issues that require manual intervention and cannot be resolved automatically.

Suspect (5 codes)

Potentially problematic configurations that warrant review.

Conflict (6 codes)

Competing or contradictory configuration requirements that produce conflicts.

Summary

Related

• ./glossary.md

Ignored

Source: https://syncpack.dev/semver-groups/ignored/

Instructs syncpack to completely disregard version range validation and enforcement for matched dependencies. Useful as a temporary workaround for dependencies that cannot yet conform to your standard semver rules.

Configuration Example

{
  "semverGroups": [
    {
      "packages": ["oops-moment", "workaround"],
      "isIgnored": true
    }
  ]
}

Properties

isIgnored (required)

Must be set to true to activate this group type. Marks all matched dependencies as excluded from semver validation.

dependencies

Names of dependencies to match. Accepts exact names and glob patterns.

Examples: ["@aws-sdk/**"], ["react", "react-dom"], ["**"]

dependencyTypes

Restricts matching to specific package.json property paths. Supports negation with ! prefix.

Valid values: "dev", "prod", "peer", "resolutions", "overrides", "pnpmOverrides", "local"

Example: ["!dev", "!prod"] — matches everything except dependencies and devDependencies.

specifierTypes

Restricts matching to dependencies with specific version specifier formats. Supports negation.

Example: ["!latest", "!file"] — excludes * and file: specifiers.

label

A short descriptive name displayed as a header in syncpack output.

packages

Filters by the name property in package.json files. Accepts exact names and glob patterns. Supports negation but cannot mix negated and non-negated entries in the same array.

Valid: ["@my-repo/**"], ["my-server", "my-client"] Invalid: filesystem paths, ["my-client", "!@my-repo/**"]

Notes

• Each dependency matches only the first semver group whose criteria it satisfies.
• isIgnored groups do not enforce any range format — matched dependencies are silently skipped during all semver checks.
• Use this group as a short-term workaround; prefer fixing the root cause over permanent ignore rules.

Related

• With Range
• README

semver-groups

With Range

Source: https://syncpack.dev/semver-groups/with-range/

Enforces that all matched dependencies use a specific semantic versioning range format. Use this to standardize whether versions are pinned exactly, use tilde (~), caret (^), or another supported format.

Configuration Example

{
  "semverGroups": [
    {
      "dependencies": ["@foo/**"],
      "range": "~"
    }
  ]
}

Properties

range (required)

Specifies the semver range format to enforce for all matched dependencies.

dependencies

Names of dependencies to match. Accepts exact names and glob patterns.

Examples: ["**"], ["@aws-sdk/**"], ["react", "react-dom"]

Supported package.json locations scanned for dependency names: name, dependencies, devDependencies, overrides, peerDependencies, pnpm.overrides, resolutions.

dependencyTypes

Restricts matching to specific package.json property paths. Supports negation with ! prefix.

Valid values: "dev", "prod", "peer", "resolutions", "overrides", "pnpmOverrides", "local"

Example: ["!dev", "!prod"] — matches everything except dependencies and devDependencies.

specifierTypes

Filters dependencies by version specifier format. Supports negation.

Example: ["!latest", "!file"] — excludes * and file: specifiers while including all others.

label

A short descriptive name displayed as a header in syncpack output.

packages

Filters by the name property in package.json files. Accepts exact names and glob patterns. Supports negation but cannot mix negated and non-negated entries in the same array.

Valid: ["**"], ["@my-repo/**"], ["my-server", "my-client"] Invalid: filesystem paths, mixed negation arrays

Notes

• Each dependency matches only the first semver group whose criteria it satisfies — order matters.
• syncpack will report and optionally fix any dependency that does not match the configured range format.
• When dependencies, dependencyTypes, packages, and specifierTypes are all omitted, the group matches everything — useful as a catch-all default rule at the end of the semverGroups array.

Related

• Ignored
• README

ignored (Update Group)

Source: https://syncpack.dev/update-groups/ignored/

Exclude specific dependencies from registry update checks. Dependencies matching this group are marked as valid and won't be offered as update candidates, even when newer versions exist on npm.

Usage

{
  "updateGroups": [
    {
      "dependencyTypes": ["peer"],
      "isIgnored": true
    }
  ]
}

Options

Notes

• Particularly useful for peer dependencies, where the consuming project controls the version range rather than the publisher
• Added in v15.1.1

Related

• targeted
• update command

Update Groups

Control how and whether dependencies receive updates from the npm registry via the update command. Groups are evaluated sequentially; the first matching group applies. The stricter of the CLI --target and group target wins.

Common Filter Properties

All update groups share these optional filter properties:

targeted (Update Group)

Source: https://syncpack.dev/update-groups/targeted/

Restrict the highest registry update offered for matched dependencies. The stricter of the CLI --target flag and the group's target setting wins — a group with target: "latest" cannot override a CLI invocation using --target patch.

Usage

{
  "updateGroups": [
    {
      "label": "Restrict Storybook to patch updates",
      "dependencies": ["@storybook/**"],
      "target": "patch"
    },
    {
      "label": "Minor updates only for devDependencies",
      "dependencyTypes": ["dev"],
      "target": "minor"
    }
  ]
}

Options

Target Values

Notes

• Added in v15.1.1
• Patterns match against dependencies, devDependencies, overrides, peerDependencies, and pnpm/Bun catalog locations

Related

• ignored
• update command

Banned

Source: https://syncpack.dev/version-groups/banned/

Prevent dependencies you've decided should never be used. Flags them as issues requiring removal — useful for enforcing policies against legacy packages, conflicting libraries, or security/licensing violations.

Activation

Set isBanned: true in a version group entry.

Configuration Properties

dependencyTypes values

dependencies, devDependencies, overrides, peerDependencies, pnpm.overrides, resolutions

Negation example: ["!dev", "!prod"]

dependencies glob examples

• ["**"] — all dependencies
• ["@aws-sdk/**"] — scoped packages
• ["react", "react-dom"] — specific packages

packages glob examples

• ["**"] — all packages
• ["@my-repo/**"] — scoped packages
• ["my-server", "my-client"] — specific packages

Configuration Example

{
  "versionGroups": [
    {
      "dependencies": ["never-gonna"],
      "isBanned": true
    }
  ]
}

Status Codes

Notes

• Local packages cannot be banned; syncpack will flag RefuseToBanLocal instead of IsBanned.
• IsBanned is "fixable" in the sense that syncpack can report it, but the fix requires manually removing the dependency — syncpack does not auto-remove entries.

catalog

Source: https://syncpack.dev/version-groups/catalog/

Enforce dependencies to be defined in pnpm or Bun catalogs and consumed via the catalog: protocol. Establishes a single source of truth for dependency versions across the monorepo.

Usage

{
  "versionGroups": [
    {
      "policy": "catalog"
    }
  ]
}

Options

Behavior

Syncpack automatically:

• Flags dependencies using literal version specifiers instead of catalog references
• Replaces mismatched versions with appropriate catalog: pointers during fix
• Inserts missing dependencies into the catalog
• Creates implicit default catalogs for pnpm/Bun projects

Status Codes

Notes

• Added in v15.0.0 with full support for pnpm and Bun catalog: protocol
• pnpmOverrides now reads from pnpm-workspace.yaml instead of package.json (v15 breaking change)

Related

• pinned
• snapped-to
• source

Highest Semver

Source: https://syncpack.dev/version-groups/highest-semver/

Ensures all instances of a dependency across the monorepo align to the highest semantic version found. When version discrepancies exist, syncpack standardizes them upward to the maximum installed version.

Activation

This is the default policy when no other policy property is specified in a version group. No special property is required, but you can also set preferVersion: "highestSemver" explicitly.

Configuration Properties

dependencyTypes negation example

["!dev", "!prod"]

Excludes devDependencies and dependencies, matching only the remaining locations.

specifierTypes negation example

["!latest", "!file"]

Excludes wildcard and file-path specifiers.

Configuration Example

{
  "versionGroups": [
    {
      "dependencies": ["react", "react-dom"],
      "preferVersion": "highestSemver"
    }
  ]
}

Status Codes

Ignored

Source: https://syncpack.dev/version-groups/ignored/

Completely excludes specified dependencies from all validation and synchronization checks. Useful for incrementally adopting syncpack — handle known-fixable dependencies first, then ignore the rest.

Activation

Set isIgnored: true in a version group entry.

Configuration Properties

dependencyTypes values

dependencies, devDependencies, overrides, peerDependencies, pnpm.overrides, resolutions

Negation example: ["!dev", "!prod"]

specifierTypes negation example

["!latest", "!file"]

Configuration Example

{
  "versionGroups": [
    {
      "dependencies": ["keep-walking"],
      "isIgnored": true
    }
  ]
}

Status Codes

Notes

• Ignored dependencies produce no warnings or errors — they are completely invisible to syncpack.
• A common pattern is to add a catch-all isIgnored group at the bottom of versionGroups to silence everything not yet handled by other groups.

Lowest Semver

Source: https://syncpack.dev/version-groups/lowest-semver/

Ensures all instances of a dependency across the monorepo align to the lowest semantic version found. When version discrepancies exist, syncpack updates them down to the minimum installed version.

Activation

Set preferVersion: "lowestSemver" in a version group entry.

Configuration Properties

dependencyTypes values

dependencies, devDependencies, overrides, peerDependencies, pnpm.overrides, resolutions

Negation example: ["!dev", "!prod"]

dependencies glob examples

• ["react", "react-dom"] — specific packages
• ["@aws-sdk/**"] — scoped packages
• ["**"] — all packages

Configuration Example

{
  "versionGroups": [
    {
      "dependencies": ["swing", "low"],
      "preferVersion": "lowestSemver"
    }
  ]
}

Status Codes

Pinned

Source: https://syncpack.dev/version-groups/pinned/

Locks dependencies to a specific version specifier across the entire project, regardless of what versions are used elsewhere. The pinned version can be any specifier supported by a package manager (exact version, range, tag, etc.).

Activation

Set pinVersion to the desired version specifier string.

Configuration Properties

dependencyTypes values

dependencies, devDependencies, overrides, peerDependencies, pnpm.overrides, resolutions

Negation example: ["!dev", "!prod"]

packages glob examples

• ["**"] — all packages
• ["@my-repo/**"] — scoped packages
• ["my-server", "my-client"] — specific packages

Configuration Example

{
  "versionGroups": [
    {
      "dependencies": ["@types/node"],
      "pinVersion": "18.14.2"
    }
  ]
}

Status Codes

Notes

• pinVersion accepts any package manager-supported specifier, not only exact versions. You can pin to ranges like "^18.0.0" or tags like "latest".
• Local packages cannot be pinned; syncpack will flag RefuseToPinLocal.

range-only

Source: https://syncpack.dev/version-groups/range-only/

Enforce consistent semver range prefixes (^, ~, exact, etc.) across matched dependencies without syncing actual version numbers. Unlike sameRange, which verifies overlapping version compatibility, this policy only validates the prefix format.

Usage

{
  "versionGroups": [
    {
      "policy": "semverRangeOnly"
    }
  ]
}

Options

Status Codes

Example with semver group coordination

{
  "semverGroups": [
    {
      "label": "Use exact versions for prod",
      "dependencyTypes": ["prod"],
      "range": ""
    },
    {
      "label": "Use ~ for devDependencies",
      "dependencyTypes": ["dev"],
      "range": "~"
    }
  ],
  "versionGroups": [
    {
      "label": "Only enforce semver ranges",
      "policy": "semverRangeOnly"
    }
  ]
}

Notes

• Added in v15.3.0
• When updates occur, the registry version receives the semver group's designated prefix automatically

Related

• same-range
• semver-groups

Version Groups

Same Minor

Source: https://syncpack.dev/version-groups/same-minor/

Ensures that dependencies maintain matching MAJOR.MINOR.x version numbers across the monorepo while permitting different patch versions. Only ~ (tilde) and exact version specifiers are allowed, as other range types could permit installations outside the intended version band.

Activation

Set policy: "sameMinor" in a version group entry.

Configuration Properties

preferVersion values

Warning: Setting preferVersion loosens requirements and risks issues with 0.x.x versions or non-compliant semantic versioning.

dependencyTypes negation example

["!dev", "!prod"]

Configuration Example

{
  "versionGroups": [
    {
      "dependencies": ["@aws-sdk/**"],
      "policy": "sameMinor"
    }
  ]
}

Status Codes

Notes

• This policy results in multiple package installations for each distinct patch version, which may increase node_modules complexity.
• Primarily useful when aliasing related packages (e.g., @aws-sdk/**) that may legitimately have different patch versions within the same minor release.
• Only ~x.x.x and exact x.x.x specifiers are valid under this policy.

Same Range

Source: https://syncpack.dev/version-groups/same-range/

Ensures all instances of a dependency across the monorepo use semver ranges that intersect (overlap) with each other. Ranges don't need to be identical — they just need to share at least one version in common. This is the most permissive version group policy in syncpack.

Activation

Set policy: "sameRange" in a version group entry.

Configuration Properties

Intersection Examples

Overlapping ranges (valid):

Non-overlapping ranges (invalid):

Configuration Example

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

Status Codes

Notes

• sameRange only works with semver ranges (e.g., ^1.2.3, >=1.0.0, ~2.0.0). Exact pinned versions like 1.0.0 and 1.0.1 are treated as non-overlapping ranges.
• Mismatches (SameRangeMismatch) are not auto-fixable because syncpack cannot determine which range should change.
• Common use cases:
• Peer dependencies where packages legitimately need varying ranges
• Type packages (e.g., foo and @types/foo) on different release schedules

Snapped To

Source: https://syncpack.dev/version-groups/snapped-to/

Synchronizes dependency versions across packages by following a designated source package. Dependencies in this group adopt versions from the specified "snap" packages, ensuring consistency across a monorepo by treating one or more packages as the authoritative version source.

Activation

Set snapTo to an array of package names that serve as version sources.

Configuration Properties

snapTo fallback behavior

When multiple packages are listed in snapTo, syncpack looks for the dependency in each package in order and uses the first match found:

{
  "snapTo": ["primary-app", "secondary-app"]
}

If a dependency is not present in primary-app, its version is taken from secondary-app.

dependencyTypes negation example

["!dev", "!prod"]

packages negation example

["!my-client", "!my-server"]

Configuration Example

{
  "versionGroups": [
    {
      "dependencies": ["react", "react-native"],
      "snapTo": ["mobile-app"]
    }
  ]
}

Status Codes

Notes

• The packages listed in snapTo are referenced by their name field in package.json, not by their directory path.
• Local packages cannot be snapped; syncpack will flag RefuseToSnapLocal.
• If the snap target package does not exist in the monorepo, DependsOnMissingSnapTarget is reported.

Ban Dependency

Flag disallowed packages so they are reported as issues and must be removed.

{
  "versionGroups": [
    {
      "label": "Ban legacy or disallowed packages",
      "dependencies": ["moment", "lodash"],
      "isBanned": true
    }
  ]
}

# Report banned dependencies
syncpack lint

# Verify the specific packages are flagged
syncpack lint --dependencies moment

Notes

• IsBanned is reported as a fixable issue, but syncpack does not auto-remove entries — manual deletion is required
• Local (workspace) packages cannot be banned; RefuseToBanLocal is reported instead
• Glob patterns are supported in dependencies (e.g., ["@deprecated/**"])
• Useful for enforcing policies against security violations, conflicting libraries, or migration targets

Basic Lint and Fix

Check for version mismatches across the monorepo and auto-fix them.

# Check all dependency types for issues
syncpack lint

# Auto-fix all identified mismatches
syncpack fix

# Preview changes without writing to disk
syncpack fix --dry-run

# After fixing, refresh lockfiles
npm install

Notes

• lint exits with code 1 when issues are found, making it suitable for CI gating
• fix handles version alignment only; use format separately for field ordering
• Always run the package manager install after fix or update to refresh lockfiles
• Use --dependency-types prod,dev to narrow scope to specific dependency categories

CI Workflow

Run syncpack checks in CI to enforce version consistency and formatting before merging.

# .github/workflows/syncpack.yml
name: Syncpack

on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: Lint version consistency
        run: npx syncpack lint
      - name: Check package.json formatting
        run: npx syncpack format --check
      - name: Check for outdated dependencies
        run: npx syncpack update --check --target minor

Notes

• syncpack lint and syncpack format --check exit with code 1 on issues, failing the CI job automatically
• syncpack update --check reports outdated packages without modifying files
• Use npx syncpack to run without a local install, or add syncpack to root devDependencies for caching
• Add --dependency-types prod,dev to narrow lint scope and reduce noise in CI output

Custom Types

Extend syncpack to manage non-standard package.json fields such as engines or packageManager.

{
  "customTypes": {
    "engines": {
      "strategy": "versionsByName",
      "path": "engines"
    },
    "packageManager": {
      "strategy": "name@version",
      "path": "packageManager"
    }
  },
  "versionGroups": [
    {
      "label": "Sync Node.js engine requirement",
      "dependencies": ["node"],
      "dependencyTypes": ["engines"]
    },
    {
      "label": "Sync packageManager field",
      "dependencies": ["pnpm"],
      "dependencyTypes": ["packageManager"]
    }
  ]
}

# Lint only custom types
syncpack lint --dependency-types engines,packageManager

Notes

• versionsByName strategy reads fields like { "node": ">=18" }; name@version reads "pnpm@9.0.0" strings
• Custom type names defined in customTypes can be referenced by name in --dependency-types CLI option
• Nested paths use dot notation (e.g., "some.nested.property")
• Custom types work with dependencyTypes in version groups, semver groups, and dependency groups

Format package.json

Sort and standardize package.json fields consistently across all monorepo packages.

# Apply formatting to all package.json files
syncpack format

# Check formatting without modifying files (exits with code 1 if issues found)
syncpack format --check

# Check a specific package
syncpack format --check --source 'packages/my-app/package.json'

{
  "indent": "    ",
  "sortFirst": ["name", "version", "description", "main", "scripts"],
  "sortAz": ["dependencies", "devDependencies", "peerDependencies"]
}

Notes

• format sorts fields and alphabetizes nested properties but does not modify version numbers
• --check is suitable for CI enforcement of package.json style consistency
• sortFirst controls the order of top-level fields that appear before alphabetical sorting
• sortAz alphabetizes the named fields; dependency objects are a common target

Minimal Config

Start with a narrow scope targeting production dependencies, then expand gradually.

{
  "$schema": "./node_modules/syncpack/schema.json",
  "versionGroups": [
    {
      "label": "Sync all production dependencies",
      "dependencyTypes": ["prod"]
    },
    {
      "label": "Ignore everything else",
      "isIgnored": true
    }
  ]
}

Notes

• Place .syncpackrc (JSON format) at the monorepo root for fastest performance
• The $schema property enables IDE autocompletion
• The final isIgnored catch-all prevents unintended linting of unscoped dependencies
• TypeScript and JavaScript config formats (syncpack.config.ts, .syncpackrc.js) are also supported

Pin Version

Lock a specific dependency to an exact version across the entire monorepo.

{
  "versionGroups": [
    {
      "label": "Pin @types/node to LTS version",
      "dependencies": ["@types/node"],
      "pinVersion": "18.14.2"
    },
    {
      "label": "Pin all AWS SDK packages to the same range",
      "dependencies": ["@aws-sdk/**"],
      "pinVersion": "^3.0.0"
    }
  ]
}

# Detect and fix any deviation from the pin
syncpack fix --dependencies @types/node

Notes

• pinVersion accepts any package manager-supported specifier: exact versions, ranges (^, ~), or tags (latest)
• DiffersToPin is reported when a package deviates from the pinned value and can be auto-corrected by syncpack fix
• PinOverridesSemverRange is reported when the pin conflicts with an existing semver range
• Local packages cannot be pinned; RefuseToPinLocal is reported instead

samples

Semver Range Policy

Enforce consistent semver range formats across dependency types (e.g., ^ for devDependencies, ~ for prod).

{
  "semverGroups": [
    {
      "label": "Use ~ for production dependencies",
      "dependencyTypes": ["prod"],
      "range": "~"
    },
    {
      "label": "Use ^ for dev dependencies",
      "dependencyTypes": ["dev"],
      "range": "^"
    },
    {
      "label": "Pin exact versions for scoped packages",
      "dependencies": ["@my-org/**"],
      "range": ""
    }
  ]
}

Notes

• range: "" enforces exact pinning (e.g., 1.2.3); "~" allows patch updates; "^" allows minor updates
• Each dependency matches only the first semver group whose criteria it satisfies — order matters
• A catch-all group at the end (with no filters) acts as the default rule for unmatched dependencies
• Run syncpack lint then syncpack fix to detect and apply range corrections

Snap to Source

Synchronize dependency versions across packages by treating one package as the authoritative version source.

{
  "versionGroups": [
    {
      "label": "Snap React versions to match mobile-app",
      "dependencies": ["react", "react-dom", "react-native"],
      "snapTo": ["mobile-app"]
    },
    {
      "label": "Snap shared deps to root, fall back to web-app",
      "dependencies": ["typescript", "eslint"],
      "snapTo": ["root-package", "web-app"]
    }
  ]
}

Notes

• snapTo references package name fields from package.json, not directory paths
• When multiple packages are listed in snapTo, syncpack checks each in order and uses the first match found (fallback behavior)
• DiffersToSnapTarget is reported when versions differ and can be auto-corrected by syncpack fix
• Local packages cannot be snapped; RefuseToSnapLocal is reported instead
• If the snap target does not exist in the monorepo, DependsOnMissingSnapTarget is reported

Update Dependencies

Fetch newer versions from the npm registry and apply them across the monorepo.

# Check what updates are available without modifying files
syncpack update --check

# Apply only patch-level updates for devDependencies
syncpack update --dependency-types dev --target patch

# Apply minor updates for a specific package
syncpack update --dependencies react --target minor

# Interactively approve each update
syncpack update --interactive

# Check for updates in a specific scope
syncpack update --check --dependencies '@aws-sdk/**'

# After updating, refresh lockfiles
pnpm install

Notes

• --check exits with code 1 when outdated dependencies are found, suitable for CI
• --target patch updates only within the current minor (1.2.x); --target minor updates within the major (1.x.x); --target latest accepts any update
• --interactive allows keyboard selection of which updates to apply
• Use updateGroups in .syncpackrc for per-dependency update policies

Workspace Protocol

Enforce workspace:* for all internal package references across the monorepo.

{
  "versionGroups": [
    {
      "label": "Use workspace:* protocol for local packages",
      "dependencies": ["$LOCAL"],
      "dependencyTypes": ["dev", "prod"],
      "pinVersion": "workspace:*"
    },
    {
      "label": "Ignore everything else",
      "isIgnored": true
    }
  ]
}

Notes

• $LOCAL is a built-in placeholder that matches all packages defined within the monorepo
• pinVersion can be any specifier supported by the package manager, not only exact versions
• Syncpack flags RefuseToPinLocal if a local package is in a version group that cannot apply to it
• Compatible with pnpm, Yarn, and Bun workspace protocols

CLI

syncpack の全 CLI コマンドとよく使うオプション

依存関係の一覧表示

syncpack list

依存関係の一覧表示（本番依存のみ・件数順）

syncpack list --dependency-types prod --sort count

依存関係の一覧表示（glob フィルター）

syncpack list --dependencies '**eslint**'
syncpack list --dependencies '@types/**'

バージョン不一致の検出

syncpack lint

本番・開発依存のみ検査する場合:

syncpack lint --dependency-types prod,dev

バージョン不一致の自動修正

syncpack fix

警告: package.json を直接書き換える。実行後は npm install / pnpm install 等でロックファイルを更新すること。

特定の依存関係のみ修正する場合:

syncpack fix --dependencies react
syncpack fix --dependencies '@types/**'

依存カテゴリを絞って修正する場合:

syncpack fix --dependency-types prod,dev

変更をプレビュー（ファイルを書き換えない）:

syncpack fix --dry-run

package.json のフォーマット（整形）

syncpack format

警告: package.json のフィールド順・アルファベット順を書き換える。バージョン番号は変更しない。

フォーマット確認のみ（ファイルを書き換えない）:

syncpack format --check

特定パッケージのみ確認する場合:

syncpack format --check --source 'packages/pingu/package.json'

npm レジストリから最新バージョンへ更新

syncpack update --target latest

警告: npm レジストリへのネットワークアクセスが必要。package.json を直接書き換える。実行後は npm install / pnpm install 等でロックファイルを更新すること。

更新範囲を制限する場合:

# マイナーバージョンまで（1.x.x）
syncpack update --target minor

# パッチバージョンまで（1.2.x）
syncpack update --target patch

更新の確認のみ（ファイルを書き換えない）:

syncpack update --check
syncpack update --check --dependencies react
syncpack update --check --dependency-types dev --target patch

特定依存関係のみ更新する場合:

syncpack update --dependencies react
syncpack update --dependencies '@aws-sdk/**'

依存関係情報を JSON で出力

syncpack json

特定依存関係のみ出力する場合:

syncpack json --dependencies '@aws-sdk/**'

jq と組み合わせる場合:

syncpack json | jq -r '.dependencyType' | sort | uniq -c

ヘルプの表示

# 簡易サマリー
syncpack lint -h

# 詳細ドキュメント
syncpack lint --help

lint の部分を fix / format / list / update / json に変えて各コマンドのヘルプを確認できる。

共通オプション

全コマンドで利用できる代表的なオプション:

Install

syncpack のインストールとセットアップ

npx で試す（インストール不要）

npx syncpack list --dependency-types prod

モノレポルートで実行する。インストールなしで動作確認できる。

npm でインストール

npm install syncpack --save-dev

ローカルインストール済みバイナリの実行

npm exec syncpack -- list

設定ファイルの作成

.syncpackrc をリポジトリルートに作成する。JSON / YAML / JS / TS / MJS / CJS いずれかの形式で記述する。

# package.json の syncpack プロパティに設定を埋め込む場合は追加ファイル不要
# カスタムパスを指定する場合（拡張子必須）
syncpack list --config ./config/syncpack.json

scripts