One Version

One Version is a strict dependency conformance tool for monorepos, managing dependencies across repos has never been easier!

This tool ensures that all workspaces in your monorepo are using the same version of a dependency, and also an (opt-in) strict versioning strategy to ensure that all dependencies are pinned to an exact version.

Get Started Star on GitHub

Installation

Install one-version via your favorite package manager:

bun install one-version
bun install one-version

Notably! one-version should be installed at the root of your monorepo.

Usage:

Once you've installed one-version, you can add a one-version:check script in your root package.json:

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

You can now run bun run one-version:check (or use whatever package manager you have setup) to check for version conformance!

Configuration:

one-version can work out of the box without any configuration at all, however if you'd like to allow specific workspaces to use different versions of a dependency, you'll need to add a configuration file.

one-version currently supports the following package managers:

You can configure one-version via either a one-version.config.jsonc or one-version.config.json file. An example configuration is provided below:

{
  "$schema": "https://one-version.vercel.app/schema.json",
  // one of: "bun", "yarn-berry", "yarn-classic", "pnpm", "npm"
  // by default it will try to detect the package manager based on the presence of a lockfile
  "packageManager": "bun",
  // A mapping of dependencies, and which workspaces are "allowed" to use different versions
  "overrides": {
    "react": {
      "18.0.0": ["pkg-a"],
      // Wildcards are supported, and will capture any workspaces!
      "17.0.0": ["*"]
    }
  },
  // one of: "pin", "loose", defaults to "loose" if not provided
  // pin: all dependencies and devDependencies must use an exact version
  // meaning no ranges (`^`, `~`, `.x`, etc.) are allowed
  "versionStrategy": "pin"
}
{
  "$schema": "https://one-version.vercel.app/schema.json",
  // one of: "bun", "yarn-berry", "yarn-classic", "pnpm", "npm"
  // by default it will try to detect the package manager based on the presence of a lockfile
  "packageManager": "bun",
  // A mapping of dependencies, and which workspaces are "allowed" to use different versions
  "overrides": {
    "react": {
      "18.0.0": ["pkg-a"],
      // Wildcards are supported, and will capture any workspaces!
      "17.0.0": ["*"]
    }
  },
  // one of: "pin", "loose", defaults to "loose" if not provided
  // pin: all dependencies and devDependencies must use an exact version
  // meaning no ranges (`^`, `~`, `.x`, etc.) are allowed
  "versionStrategy": "pin"
}

Background and Inspiration:

This package is a spiritual fork of the @wayfair/one-version package which I had contributed to while at Wayfair.

That package still works fine, but hasn't been maintained in some time - and also doesn't support either bun or npm.

Both this package and the original implement a version of Google's One-Version Rule:

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

[1] - Software Engineering At Google - Winters, Manshreck and Wright, 2020, p. 341