dep-sync

Sync dependency versions across multiple projects. Perfect for monorepos and managing multiple React/Node.js applications.

Installation

# Global install
npm install -g dep-sync

# Or use with npx
npx dep-sync react 18.2.0 --paths ./apps/*

Usage

Basic usage

dep-sync react 18.2.0 --paths ./apps/app1 --paths ./apps/app2

With exact version (no ^ prefix)

dep-sync react 18.2.0 --paths ./apps/* --exact

Dry-run mode (preview changes)

dep-sync react 18.2.0 --paths ./apps/* --dry-run

Multiple packages

# Using --pkg flag (repeatable)
dep-sync --pkg [email protected] --pkg [email protected] --paths ./apps/*

Using a config file

dep-sync --config dep-sync.config.json

Supports .json, .js, .mjs, and .cjs config files. JSON is recommended as it works in any project without module system issues.

Example JSON config (recommended):

{
  "packages": {
    "react": "18.2.0",
    "react-dom": "18.2.0"
  },
  "paths": [
    "./apps/app1",
    "./apps/app2"
  ],
  "exact": false
}

Example JavaScript config (ES module - requires "type": "module" in package.json or use .mjs extension):

export default {
  packages: {
    "react": "18.2.0",
    "react-dom": "18.2.0",
    "@types/react": "18.2.0",
  },
  paths: [
    "./apps/app1",
    "./apps/app2",
  ],
  exact: false,
};

Interactive mode

dep-sync --interactive --paths ./apps/*

# Combine with config file (config provides defaults)
dep-sync --interactive --config dep-sync.config.json

Interactive mode guides you through:

• Operation selection: Update packages, bump versions, or both
• Package updates: Package name, target version, project selection
• Version bumping: Bump type (patch/minor/major/prerelease) and preid
• Git options: Commit and push prompts

When combined with --config, the config file provides default values (paths, packages, etc.) that you can override interactively.

Git integration

# Git sync (fetch + pull --rebase) runs by default
# Repos are synced automatically before updates

# Skip git sync
dep-sync react 18.2.0 --paths ./apps/* --no-sync

# Commit changes (single commit for all dependency updates)
dep-sync --pkg [email protected] --pkg [email protected] --paths ./apps/* --commit

# Commit and push to remote
dep-sync react 18.2.0 --paths ./apps/* --commit --push

# Create branch, commit, and push
dep-sync react 18.2.0 --paths ./apps/* --commit --branch chore/react-18 --push

# Custom commit message
dep-sync react 18.2.0 --paths ./apps/* --commit --message "chore(deps): upgrade react"

Bump project versions

Automatically bump the version field in each project's package.json after updating dependencies. Version bumps use npm version which creates a commit and git tag (e.g., v1.0.1) for each project:

# Patch version bump (1.0.0 → 1.0.1)
dep-sync react 18.2.0 --paths ./apps/* --commit --bump-version patch

# Minor version bump (1.0.0 → 1.1.0)
dep-sync react 18.2.0 --paths ./apps/* --commit --bump-version minor

# Major version bump (1.0.0 → 2.0.0)
dep-sync react 18.2.0 --paths ./apps/* --commit --bump-version major

# Prerelease bump with custom identifier (1.0.0 → 1.0.1-rc.0)
dep-sync react 18.2.0 --paths ./apps/* --commit --bump-version prerelease --preid rc

# Prerelease with beta tag (1.0.0 → 1.0.1-beta.0)
dep-sync react 18.2.0 --paths ./apps/* --commit --bump-version prerelease --preid beta

Note: Version bumps are only applied to projects that had dependency updates. Prerelease bumps correctly increment: 1.0.1-rc.2 → 1.0.1-rc.3

Standalone version bump

Bump project versions without updating any dependencies:

# Bump all projects to next patch version
dep-sync --bump-version patch --paths ./apps/*

# Bump to prerelease with push
dep-sync --bump-version prerelease --preid rc --paths ./apps/* --push

Or use a config file for version bumps only:

{
  "paths": ["./apps/app1", "./apps/app2"],
  "bumpVersion": "prerelease",
  "preid": "rc"
}

dep-sync --config dep-sync.config.json

Options

| Option | Description | |--------|-------------| | --pkg <name@version> | Package to update (repeatable for multiple packages) | | --paths <paths...> | Paths to project directories | | --exact | Use exact version (no ^ or ~ prefix) | | --dry-run | Preview changes without modifying files | | --no-peer | Skip peerDependencies | | --no-sync | Skip git fetch/pull before updating (sync is ON by default) | | --commit | Commit dependency changes (single commit for all packages) | | --push | Push to remote after committing (skips repos that are behind) | | --message <msg> | Custom commit message | | --branch <name> | Create a new branch before committing | | --bump-version <type> | Bump version in each project's package.json (patch|minor|major|prerelease) | | --preid <tag> | Prerelease identifier (e.g., rc, beta, alpha). Used with --bump-version prerelease | | --config <path> | Path to config file | | --interactive, -i | Run in interactive mode | | --version, -v, -V | Show version number | | --help | Show help message |

Note: The package will be automatically updated in all dependency types where it exists (dependencies, devDependencies, peerDependencies, optionalDependencies). peerDependencies always use caret (^) to preserve range semantics.

Example output

Updating react to ^18.2.0

✔ app1 (deps, devDeps)
  deps: ^18.1.0 → ^18.2.0
  devDeps: ^18.1.0 → ^18.2.0

✔ sdk-package (deps, peerDeps)
  deps: ^18.1.0 → ^18.2.0
  peerDeps: ^17.0.0 || ^18.0.0 → ^18.2.0 (range preserved)

⚠ legacy-app: react not found

Summary:
  ✔ Updated: 2
  ⚠ Not found: 1

License

MIT