Syncpack

14.3.0 · active · verified Sun Apr 19

Syncpack is a robust CLI tool and library designed to enforce consistent dependency versions across large JavaScript and TypeScript monorepos. Currently at stable version 14.3.0, it maintains a regular and active release cadence with several updates, including patches and minor features, issued monthly. Its core functionality includes linting for version inconsistencies, automatically fixing them, and updating dependencies to the latest available versions while preserving semver ranges. Syncpack differentiates itself through its deep integration with various monorepo tools like Lerna, Nx, and pnpm, and its recent rewrite in Rust for version 14 significantly improved performance and introduced a new, more modular API. It is widely adopted by organizations such as AWS, Microsoft, and Vercel for maintaining their large-scale projects.

Common errors

```
Error: Command 'x' not found or 'y' is not a valid option
```
cause Attempting to use pre-v14 CLI commands or options after upgrading to Syncpack v14, which introduced a new command-line interface and API.

fix Refer to the Syncpack v14 documentation for the updated CLI commands and options. Many commands were renamed or restructured.
```
Error: Syncpack encountered an issue related to pnpm workspaces (specific error message might vary)
```
cause Running Syncpack versions 14.0.0 or 14.0.1 with pnpm due to a bug in handling glob patterns or package resolution.

fix Upgrade your Syncpack dependency to version 14.0.2 or higher to resolve known pnpm compatibility issues.
```
TypeError: (0 , syncpack_1.lint) is not a function or Module not found: Error: Can't resolve 'syncpack'
```
cause Incorrect programmatic import path or CommonJS `require()` syntax being used for Syncpack's ESM-only exports in v14+.

fix Ensure you are using `import { lint } from 'syncpack/cli'` (or other command names) for programmatic access, and that your project is configured for ESM if using Node.js.

Warnings

breaking Syncpack v14 is a complete rewrite in Rust, introducing a new API and CLI command structure. Older configurations and programmatic integrations will likely break.
Fix: Consult the official 'Migrate to 14' guide on syncpack.dev. Update CLI commands and programmatic imports to the new 'syncpack/cli' entry points.
gotcha Pnpm users on Syncpack versions 14.0.0 and 14.0.1 experienced bugs due to issues with negated source globs and dependency handling.
Fix: Upgrade Syncpack to version 14.0.2 or newer to resolve pnpm-related issues.
breaking The `syncpack.config.js` now allows `//` comments, but older config file formats or specific options might have changed behavior or been deprecated.
Fix: Review your `syncpack.config.js` or `.syncpackrc` files against the latest documentation for v14 to ensure compatibility with new parsing and option structures.
gotcha Programmatic usage of Syncpack commands now returns a `Result` type (either success or error) instead of direct exceptions or boolean results.
Fix: When using `import { lint, fix } from 'syncpack/cli'`, ensure you handle the `isOk()` and `isErr()` methods on the returned object to properly manage outcomes and potential errors.

Install

npm install syncpack npm
yarn add syncpack yarn
pnpm add syncpack pnpm

Imports

lint
wrong:
```
const lint = require('syncpack/cli')
```
correct:
```
import { lint } from 'syncpack/cli'
```
Since v14, programmatic functions like 'lint' are exposed via the 'syncpack/cli' entry point. CommonJS 'require' is not supported for these ESM exports.
fix
wrong:
```
import fix from 'syncpack'
```
correct:
```
import { fix } from 'syncpack/cli'
```
Named exports from 'syncpack/cli' are the correct way to access CLI command functions programmatically in v14+. Avoid default imports from the root package.
update
```
import { update } from 'syncpack/cli'
```
The 'update' command's programmatic interface is also available as a named export from 'syncpack/cli'. Ensure you pass appropriate options objects.

Quickstart

This quickstart demonstrates setting up a minimal monorepo, installing Syncpack, identifying inconsistent dependency versions with `lint`, automatically fixing them with `fix`, and then updating all dependencies to their latest compatible versions using `update`.

npx cross-env MY_MONOREPO_ROOT="$(pwd)" bash -c '
  # 1. Initialize a new monorepo project
  mkdir my-syncpack-demo && cd my-syncpack-demo
  npm init -y &>/dev/null
  mkdir -p packages/app-a packages/app-b
  echo "{ \"name\": \"app-a\", \"version\": \"1.0.0\", \"dependencies\": { \"react\": \"18.2.0\", \"lodash\": \"^4.17.21\" } }" > packages/app-a/package.json
  echo "{ \"name\": \"app-b\", \"version\": \"1.0.0\", \"dependencies\": { \"react\": \"^18.0.0\", \"lodash\": \"4.17.15\" } }" > packages/app-b/package.json
  echo "{ \"name\": \"my-monorepo-root\", \"private\": true, \"workspaces\": [\"packages/*\"] }" > package.json

  echo "\n--- Created initial monorepo structure with inconsistent lodash versions ---"
  cat packages/app-a/package.json
  cat packages/app-b/package.json

  # 2. Install syncpack as a dev dependency in the root
  npm install --save-dev syncpack &>/dev/null
  echo "\n--- syncpack installed ---"

  # 3. Check for dependency inconsistencies
  echo "\n--- Running syncpack lint ---"
  npx syncpack lint || true # lint exits with non-zero on issues

  # 4. Fix inconsistencies across the monorepo
  echo "\n--- Running syncpack fix ---"
  npx syncpack fix

  # 5. Review the changes
  echo "\n--- package.json files after syncpack fix ---"
  cat packages/app-a/package.json
  cat packages/app-b/package.json

  # 6. (Optional) Update all dependencies to their latest compatible versions
  echo "\n--- Running syncpack update --target latest ---"
  npx syncpack update --target latest --dependency-types prod,dev

  cd $MY_MONOREPO_ROOT && rm -rf my-syncpack-demo
'

view raw JSON →