customTypes

Extend syncpack to manage other parts of your package.json files than those provided by default.

Custom types behave indentically to the default dependency types (such as prod or peer) and can be used in all of the same places.

Example: Manage `engines` property of package.json files

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.

.syncpackrc

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

.syncpackrc

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

.syncpackrc

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

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

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

Example: Synchronise Node.js version

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.

.syncpackrc

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

.syncpackrc

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

.syncpackrc

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

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

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

[name]

Required

The key of each custom type is its name, this is equivalent to the default names such as prod and dev and can be used in all of the same places those can:

1. --types and dependencyTypes
2. versionGroup.dependencyTypes
3. semverGroup.dependencyTypes

[name].path

Required

Where the version can be found in each package.json file, such as engines, packageManager or some.nested.property.

[name].strategy

Required

A strategy defines how syncpack needs to read and write dependency names and versions, there are 3 to choose from:

Name	Example
name@version	pnpm@7.27.0
version	12.4.2
versionsByName	{"pnpm":"7.27.0", "semver": "7.3.8"}