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

FAQ

How to stop an npm dependency being installed?

Ban a dependency from being used anywhere in your monorepo.

1. Add a version group

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

2. Look for mismatches

Now when you run any syncpack command, banned dependencies will be listed:

syncpack list

And can be removed:

syncpack fix-mismatches

Ensure that semver ranges for a dependency all match each other

Add a Same Range Version Group which allows local packages installed in devDependencies or peerDependencies to use different semver ranges, as long as they all match the local package version.

  • An optional label can be added to document the rule.
  • The dependencies array defines the names of the dependencies we want to target.
  • dependencyTypes results in these dependencies only being targeted by this group when they are located in devDependencies or peerDependencies.
  • The policy of sameRange states that these dependencies are considered valid if every range matches the others.
{
  "versionGroups": [
    {
      "label": "Ensure semver ranges for locally developed packages satisfy the local version",
      "dependencies": [
        "@your-repo/node-client-plugin-retry",
        "@your-repo/node-client",
        "dashboard-ui"
      ],
      "dependencyTypes": ["dev", "peer"],
      "policy": "sameRange"
    }
  ]
}

The above example can be shortened: The $LOCAL keyword is a helper to avoid writing out the names of every local package.

"dependencies": [
  "$LOCAL"
  "@your-repo/node-client-plugin-retry",
  "@your-repo/node-client",
  "dashboard-ui"
],

Ensure AWS SDK dependencies always have the same version

Pin all dependencies from @aws-sdk so that they are always identical.

1. Add a pinned version group

  • Match all dependencies whose name starts with @aws-sdk/.
  • Mark the version as being pinned to 3.272.0 in this case.
  • Add a label to document the decision/expectation.
{
  "versionGroups": [
    {
      "dependencies": ["@aws-sdk/**"],
      "pinVersion": "3.272.0",
      "label": "AWS SDK Dependencies should all have the same version"
    }
  ]
}

2. Look for mismatches

Any @aws-sdk packages which do not have the expected version can then be found:

syncpack list-mismatches

And fixed:

syncpack fix-mismatches

Fix React Native version mismatch

Add a Snapped To Version Group which allows some of the packages in your monorepo to "follow" other packages in terms of which versions they should use.

In this example we want our Mobile App package to be the single source of truth for what the versions of react and react-native should be. Every other package will be required to use the same version it does.

Here is the Version Group configuration to do it:

  • An optional label can be added to document the rule.
  • The dependencies array defines the names of the dependencies we want to target.
  • The snapTo array lists the name properties of the locally developed package.json files which should be searched for a version of react or react-native.
{
  "versionGroups": [
    {
      "label": "Always use the versions of react brought in by the Mobile App",
      "dependencies": ["react", "react-native"],
      "snapTo": ["mobile-app"]
    }
  ]
}

Hide dependencies from syncpack

Ignore one or more dependencies so that syncpack does not inspect them.

1. Add an ignored version group

  • Match 2 specific packages in the repo.
  • Match only the peerDependencies in those packages.
  • Add a label to document the decision/expectation.
{
  "versionGroups": [
    {
      "label": "Nothing to see here, will fix soon",
      "packages": ["oops-moment", "workaround"],
      "dependencyTypes": ["peer"],
      "isIgnored": true
    }
  ]
}

With this configuration in place, syncpack will now completely ignore every dependency listed under peerDependencies in the two named packages oops-moment and workaround only.

Only allow @types packages in devDependencies

Only allow TypeScript @types packages from being used anywhere other than in the devDependencies section of package.json.

1. Add a version group

  • Match all dependencies whose name starts with @types/.
  • Only match those dependencies when they appear anywhere except devDependencies.
  • Define the behaviour of this group as isBanned.
  • Add a label to document the decision/expectation.
{
  "versionGroups": [
    {
      "dependencies": ["@types/**"],
      "dependencyTypes": ["!dev"],
      "isBanned": true,
      "label": "@types packages should only be under devDependencies"
    }
  ]
}

2. Look for mismatches

Any @types packages which are in the wrong location can then be found and manually moved:

syncpack list-mismatches

Pin local versions to pnpm workspace:*

Add a Pinned Version Group so that local packages are always installed using workspace:* when they are used in devDependencies.

  • An optional label can be added to document the rule.
  • The dependencies array defines the names of the dependencies we want to target.
  • dependencyTypes results in these dependencies only being targeted by this group when they are located in devDependencies.
  • pinVersion states that these dependencies must always use workspace:*.
{
  "versionGroups": [
    {
      "label": "Use workspace protocol when developing local packages",
      "dependencies": [
        "@your-repo/node-client-plugin-retry",
        "@your-repo/node-client",
        "dashboard-ui"
      ],
      "dependencyTypes": ["dev"],
      "pinVersion": "workspace:*"
    }
  ]
}

The above example can be shortened: The $LOCAL keyword is a helper to avoid writing out the names of every local package.

"dependencies": [
  "$LOCAL"
  "@your-repo/node-client-plugin-retry",
  "@your-repo/node-client",
  "dashboard-ui"
],

Manage npm engines throughout monorepo

Add the engines property of package.json files to also be inspected by syncpack.

1. Add a custom type

I've chosen a name of engines but it can be anything you like.

{
  "customTypes": {
    "engines": {
      // ^ this is your custom name
      "path": "engines",
      "strategy": "versionsByName",
    },
  },
}

2. Look for mismatches

Perform a one-off check of all versions defined under engines in your monorepo.

syncpack list --dependency-types engines

If the versions are not identical, they can be synchronised to all use the highest of the semver versions currently in use.

syncpack fix-mismatches --dependency-types engines

3. Track them in future

Add your new custom type to your dependencyTypes.

{
  "dependencyTypes": [
    "dev"
    "engines"
    "peer"
    "prod"
  ]
}

Now when you run any syncpack command, versions under engines will also be checked.

syncpack list

4. Relax the rules (optional)

If you don't want the Node.js version to be identical in every package but do want them all to be compatible with each other, you can use a Same Range Version Group. This defines an exception which only applies to Node.js, leaving anything else found under engines unaffected.

{
  "dependencyTypes": [
    "dev"
    "engines"
    "peer"
    "prod"
  ],
  "versionGroups": [
    {
      "dependencies": ["node"],
      "dependencyTypes": ["engines"],
      "policy": "sameRange"
    }
  ]
}

Synchronise Node.js version in monorepo

Ensure engines.node version is identical in every package.

1. Add a custom type

I've chosen a name of nodeEngine but it can be anything you like.

{
  "customTypes": {
    "nodeEngine": {
      "path": "engines.node",
      "strategy": "version"
    }
  }
}

2. Look for mismatches

Perform a one-off check for every usage of engines.node in your monorepo.

syncpack list --dependency-types nodeEngine

If the versions are not identical, they can be synchronised to all use the highest of the semver versions currently in use.

syncpack fix-mismatches --dependency-types nodeEngine

3. Track them in future

Add your new custom type to your dependencyTypes at the root level. It is included in the list of all possible dependency types.

{
  "customTypes": {
    "nodeEngine": {
      "path": "engines.node",
      "strategy": "version"
    }
  },


  "dependencyTypes": [
    "dev"
    "nodeEngine"
    "peer"
    "prod"
  ]
}

Now when you run any syncpack command, engines.node will also be checked.

syncpack list

4. Relax the rules (optional)

If you don't want the Node.js version to be identical in every package but do want them all to be compatible with each other, you can use a Same Range Version Group.

Note that you do have to list your customType in dependencyTypes for it to work within versionGroups#dependencyTypes or semverGroups#dependencyTypes.

{
  "customTypes": {
    "nodeEngine": {
      "path": "engines.node",
      "strategy": "version"
    }
  },


  "dependencyTypes": [
    "dev"
    "nodeEngine"
    "peer"
    "prod"
  ],


  "versionGroups": [
    {
      "dependencyTypes": ["nodeEngine"],
      "policy": "sameRange"
    }
  ]
}

Manage monorepo packageManager version

Add support for managing versions in engines and packageManager properties of your package.json files.

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