Banned

Find and remove dependencies which you’ve decided should never be used.

Examples

Example: Completely ban a dependency from being used

Ban a dependency from being used anywhere in your monorepo.

1. Add a version group

.syncpackrc

{
  "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

Example: Ensure `@types` are only installed as `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.

.syncpackrc

{
  "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

Configuration

isBanned

Required

This property activates this behaviour for a given Version Group.

.syncpackrc

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

dependencies

Optional

• An array of names of dependencies you’ve installed or otherwise reference in your package.json files.
• If omitted, the default behaviour is to match every dependency.
• The strings can be any combination of exact matches or minimatch glob patterns:

Examples of valid values

// match any dependency
dependencies: ["**"]

// match all dependencies with a certain scope
dependencies: ["@aws-sdk/**"]

// match specific dependencies by name
dependencies: ["react", "react-dom"]

Where this pattern is matched against

{
  "name": "HERE",
  "dependencies": { "HERE": "0.0.0" },
  "devDependencies": { "HERE": "0.0.0" },
  "overrides": { "HERE": "0.0.0" },
  "peerDependencies": { "HERE": "0.0.0" },
  "pnpm": { "overrides": { "HERE": "0.0.0" } },
  "resolutions": { "HERE": "0.0.0" }
}

dependencyTypes

Optional

Tip

You can extend syncpack to inspect more parts of your package.json files by defining your own customTypes.

• When set, only dependencies present in the named locations will be assigned to this group.
• If omitted, the default behaviour is to match dependencies everywhere they are found.
• Negated types are also supported, so a value of ["!dev", "!prod"] would assign everything except dependencies and devDependencies to this group.

Default values

Value	Property in package.json
dev	devDependencies
local	version
overrides	overrides
peer	peerDependencies
pnpmOverrides	pnpm.overrides
prod	dependencies
resolutions	resolutions

specifierTypes

Optional

• When set, only dependencies whose version specifier matches the named formats will be assigned to this group.
• If omitted, the default behaviour is to match all dependencies.
• Negated types are also supported, so a value of ["!latest", "!file"] would assign everything except specifiers of the format * and file:path/to/package.tgz to this group.

Available values

Value	Example
alias	npm:foo@1.2.3
exact	8.1.2
file	file:path/to/foo.tgz, file:path/to/directory
hosted-git	git+https://github.com/user/foo, git+ssh://git@notgithub.com/user/foo#1.2.3 etc
latest	* or latest
range	^4.1.1, >=5.0.0, ~1.2.1 etc
tag	alpha, canary
unsupported	$typescript, 1.typo.wat
url	https://server.com/foo.tgz
workspace-protocol	workspace:*, workspace:~, workspace:^

label

Optional

• A short name or description displayed as a header in syncpack’s output.
• If a label is not set then eg. “Version Group 3” will be used instead.

packages

Optional

• An array of strings which should match the name properties of your package.json files.
• If omitted, the default behaviour is to match every package.
• Negated types are also supported, so a value of ["!my-client", "!my-server"] would assign everything except the packages my-client and my-server to this group.
• The strings can be any combination of exact matches or minimatch glob patterns:

Examples of valid values

// ✅ match any package name
packages: ["**"]

// ✅ match any package name with this scope
packages: ["@my-repo/**"]

// ✅ match specific packages by name
packages: ["my-server", "my-client"]

// ✅ match all packages except negated ones
packages: ["!my-server", "!@my-repo/**]

// ❌ no mixing of specific and negated packages
packages: ["my-client", "!@my-repo/**"]

// ❌ not file system paths, name properties of package.json files
packages: ["packages/my-client"]

// ❌ not file system globs, name properties of package.json files
packages: ["packages/**"]

Where this pattern is matched against

{
  "name": "HERE",
  "version": "1.0.2"
}