One Version to bring them all, and in the darkness bind them.1

🚨 Enforcement: Require all workspaces in a monorepo to conform to the One-Version rule.

📦 Supports multiple package managers: Support for yarn classic, yarn berry, and pnpm workspaces.

💥 Coordinated upgrades: Coming Soon!

Table Of Contents

• One-Version Rule
• Getting Started
• Configuration
• Contributing
• License

One-Version Rule

This package implements a version of Google's One-Version Rule:

For every dependency in [a] repository, there must be only one version of that dependency to choose.2

Please refer to the implementation notes for our specific evaluation criteria.

There is some overlap between this tool and experimental yarn constraints, without requiring use of a particular package manager.

Getting Started

Install @wayfair/one-version at the workspace root using yarn:

yarn add --dev -w @wayfair/one-version

Or pnpm:

pnpm add -save-dev -w @wayfair/one-version

Add the following section to your package.json:

{
  "scripts": {
    "one-version:check": "one-version check"
  }
}

Run yarn one-version:check or pnpm run one-version:check.

If the repo is compliant, the tool will print this message:

✨ One Version Rule Success - found no version conflicts!

If the repo is not compliant, you will see a version of this message:

🚫 One Version Rule Failure - found multiple versions of the following dependencies:

prettier
  2.1.2
    dev: @wayfair/app-a, @wayfair/app-b
  ^2.3.2
    dev: @wayfair/app-c
  2.2.1
    dev: @wayfair/lib-a

Configuration

The behavior of @wayfair/one-version can be configured by a one-version.config.json at the root of the repository.

Supported Options

overrides (optional, object)

Overrides lets workspaces opt out of the one-version rule. This may be useful while performing major upgrades.

Examples

{
  "overrides": {
    "dependency": {
      "versionSpecifier": ["workspaceA", "workspaceB"]
    }
  }
}

For example, the below config will allow app-A and lib-L to specify react@^16.9, even if the rest of the repo specifies react@^17.

{
  "overrides": {
    "react": {
      "^16.9": ["app-A", "lib-L"]
    }
  }
}

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated 💜. For contributing guidelines, please see CONTRIBUTING.md

License

Distributed under the MIT License. See LICENSE for more information.

1: J.R.R. Tolkien, 1954. Mostly.

2: Software Engineering At Google - Winters, Manshreck and Wright, 2020, p. 341