Syncpack

Syncpack is a command-line tool for consistent dependency versions in large JavaScript Monorepos, it is used by AWS, Cloudflare, DataDog, Electron, GoDaddy, LiveStore, Lottie, Microsoft, PostHog, Qwik, Raycast, Salesforce, TopTal, Vercel, VoltAgent, WooCommerce and others.

Some of the things it can do are:

• Find and fix dependency version mismatches.
• Enforce a single version policy, or create partitions with separate policies.
• Find and bump outdated versions from the npm registry.
• Ensure some dependencies always remain pinned at a specific version.
• Ban some dependencies from being used: anywhere, or in specific places.
• Define rules for where exact or loose semver ranges should be used.
• Assign packages as the source of truth for specific dependencies' versions.
• Sort and format package.json files consistently.

Try it

The fastest way to try syncpack is via npx.

npx syncpack@alpha list --dependency-types prod

Run this command from the root directory of a monorepo and it will list every dependency installed under a dependencies property of a package.json file in the project.

Syncpack uses your package manager's workspace configuration to locate your package.json files, or you can target specific files using the source configuration or --source option.

For any given command, browse a summary of its options with -h

npx syncpack@alpha update -h

or display documentation and examples with --help

npx syncpack@alpha update --help

Install

When setting up a project for real, install syncpack in devDependencies so that everyone working on your project uses the same version.

npm install syncpack@alpha --save-dev

The locally installed binary can be run using npm exec

npm exec syncpack -- list

Introduction

Note

The examples below assume syncpack is installed globally. Replace syncpack with npx syncpack@alpha if you haven't installed it or npm exec syncpack if you have installed it locally.

Let's see which dependencies we use the most.

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

Some of our dependencies might have status codes next to them, if our Terminal supports it we can command + click each error to view its documentation, or each filename to open the file.

To focus only on dependencies with errors, use lint instead of list.

syncpack lint --dependency-types prod

If the suggested changes look ok, we can autofix them.

syncpack fix --dependency-types prod

Tip

After running fix or update, run your package manager (npm install, pnpm install, etc.) to update your lockfile.

Or we could choose to only autofix one of them, for this example I've chosen react.

syncpack fix --dependency-types prod --dependencies react

All of syncpack's commands can be filtered in the same way, let's see if react needs updating.

syncpack update --check --dependencies react

Or list every dependency with eslint somewhere in the name.

syncpack list --dependencies '**eslint**'

Or every dependency published under the @types scope.

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

We can find every dependency installed with an exact version number.

syncpack list --specifier-types exact

Or look for updates to devDependencies where only the patch version is newer than what we have installed.

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

And by removing the --check option we can write the newer versions to our files.

syncpack update --dependencies react

Each command supports --help for examples and available options.

syncpack list --help

Configuration

Create a .syncpackrc file in your repo root to customise behaviour. See Configuration for all options.

Further reading

1. Read the Peer Dependencies guide if your projects uses them, it will be important to understand them from a version consistency point of view.
2. Semver Groups configuration lets you ensure for example that version numbers in devDependencies always use ^ while dependencies always use ~.
3. With Version Groups configuration you can slice up your packages and dependencies in a lot of different ways. Each group can have different versioning policies to the rest of the repo, but are each kept internally consistent and valid according to their own rules.