Best practice: How to manage versions in a package.json

It most cases it's not necessary to add a version constraint next to your packages in the package.json. Since all versions are saved in a lockfile, everyone running yarn install will get exactly the same versions. Yarn saves this lockfile as yarn.lock and npm as package-lock.json.

There are some exceptions, where you can consider adding a version constraint to the package.json:

• You are not checking the lockfile into version control (not recommended)
• A specific package has a bug in a more recent version
• You want to ensure no one upgrades a library with yarn upgrade or npm update

A drawback of this approach is, that adding new packages might also upgrade existing packages. So check your lockfile carefully when submitting a commit. Note that the approach in this card works best, if you use yarn outdated or npm outdated together with yarn upgrade some_package or npm update some_package for major updates, before running yarn upgrade or npm update on all minor and patch updates.

Examples

Bad

Copy{
  "dependencies": {
    "autosize": "^6.0.1",
    "unpoly": "^2.7.2"
  }
}

• This blocks automatic updates of autosize and unpoly when running yarn upgrade or npm update

Good

Copy{
  "dependencies": {
    "autosize": "x",
    "unpoly": "x"
  }
}

• All packages are easily updateable with yarn upgrade or npm update

Note: "unpoly": "x" and "unpoly": "*" expresses the same version constraint

Good

Copy{
  "dependencies": {
    "autosize": "x",
    "unpoly": "2.x"
  }
}

• yarn upgrade or npm update will never perform a major unpoly update unless you change this line

Note: "unpoly": "2.x" and "unpoly": "^2.7.2" expresses the same version constraint

Bad

Commit message: Fixes CVE-XYZ

Copy{
  "dependencies": {
    "autosize": ">6.0.0",
    "unpoly": "x"
  }
}

• There is no reason we have to protect us from downgrades. If anyone decides to downgrade packages, this has to be done explicitly and will never performed automatically by yarn or npm.

Good

Commit message: Version 6 of autosize has a bug when rendering large

Copy{
  "dependencies": {
    "autosize": "<6.0.0",
    "unpoly": "x"
  }
}

• Preventing upgrades in case the newest version has a bug or is for some reason not working within the project

Some notes about yarn

In case you decide switching from "unpoly": "^2.7.2" to "unpoly": "x", you need to manually edit your yarn.lock, otherwise yarn will perform an yarn upgrade within the yarn install command:

Before:

Copyunpoly@^2.7.2:
  version "2.7.2"
  resolved "https://registry.yarnpkg.com/unpoly/-/unpoly-2.7.2.tgz#55044c08bce0984c000f7cd32450af39271727de"
  integrity sha512-jfBbBRBQMCZZcNS6fckKpFunfdiTDBXW8yxRKqLs09jSrYYUDPd+YuyDoXjABXOro0aDUIMcmyTc7moc1/Z5Tw==

After:

Copyunpoly@x:
  version "2.7.2"
  resolved "https://registry.yarnpkg.com/unpoly/-/unpoly-2.7.2.tgz#55044c08bce0984c000f7cd32450af39271727de"
  integrity sha512-jfBbBRBQMCZZcNS6fckKpFunfdiTDBXW8yxRKqLs09jSrYYUDPd+YuyDoXjABXOro0aDUIMcmyTc7moc1/Z5Tw==

Some notes about npm

When running npm update it will change the package.json and the package-lock.json.

Before:

Copy{
  "dependencies": {
    "autosize": "^6.0.1",
    "unpoly": "^2.2.1"
  }
}

After:

Copy{
  "dependencies": {
    "autosize": "^6.0.1",
    "unpoly": "^2.7.2"
  }
}