@wayfair/one-version

One Version to rule them all, One Version to find them,

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

Opinionated Monorepo Dependency Management CLI

🚨 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.²

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