85

Inside a Node.js project, it's not clear to me what the correct workflow would be to upgrade a package to a major release.

Let's suppose I'm installing stylelint:

npm install --save stylelint

By default that installation puts the string "stylelint": "^8.4.1" inside my package.json file, which means that if I want to update it with npm update, I will get only minor and patch releases (8.4.2 is ok, 8.5.0 is ok, 9.0.0 is not).

If I check with npm outdated and it comes out that I could update to 9.0.0, npm update won't get me to that state because of the restriction depicted above.

So, if I want to upgrade, what am I supposed to do?

Must I manually modify my package.json to stylelint version ^9.0.0, delete the node_modules directory, and re-run npm install?

Or should I remove the ^ character to let npm update do its job?

What is the common/best practice to adopt?

3
  • 25
    As you shared npm update only takes care of only minor and patch upgrade. However, for updating the major version intentionally, you could use npm install command without uninstall or manual removal. for your e.g. npm install [email protected] or npm install stylelint@latest
    – Sourabh
    Commented Mar 8, 2019 at 5:24
  • Does this answer your question? npm check and update package if needed Commented Jun 7, 2020 at 8:26
  • Just run npm install with the new version tagged See my answer below. Commented Dec 6, 2021 at 9:00

4 Answers 4

59

Say you have "the-package" installed at version 3.x and want to upgrade to 5.x

You would do this:

npm install the-package@5

it will update package.json and package-lock.json as well.

You can also update multiple packages in one command like npm install package1@5 package2@16

To check which packages need updates, run npm outdated

0
23

So, if I want to upgrade, what am I supposed to do?

In order to update major releases you can use the npm-check-updates.

See this great answer.

1
  • 1
    npm-check-updates makes major updates, according to semver, which might have breaking changes. Use it carefully. Commented Jul 15, 2021 at 9:30
9

Or maybe I have just to remove the ^ character to let npm update do its job?

What is the common/best practice to adopt?

The most common/best practice is to never allow automatic updates to versions that have potentially breaking changes. Workflows are all over the map, from; manual test and then update packages.json, to fully automated detect, test, update and submission of packages.json.

Many Java/JavaScript environments are particularly sensitive to transitive dependency changes due to the lack of side by side versioning support. If your package brings in a breaking change of one of its own dependencies, then your package has introduced a breaking change to the system. If your 1.y.z causes an update of one of its dependencies from X.Y.Z to X+1.Y.Z it introduces a breaking change and is therefore not a stable version 1.y.z. Other packages that depend on the same package name as yours could potentially be broken whenever the developers of that package released a breaking change. Never let the world get into that state!

I recommend you study the Diamond Dependency Problem and take to heart. You should always carefully test breaking changes and never try to force them on your customers.

As pointed out by @ShaharShokrani, this answer gives a good workflow for manually updating your package. And to remain in compliance with SemVer 2.0.0 #8, don't forget to bump your own major version number.

5
  • Ok, so no particular workflow defined exept for a lot of attention doing this kind of things! :-D Thank you for your answer and suggestion!
    – caneta
    Commented Feb 22, 2018 at 9:55
  • There are lots of DevOps products out there that provide all the mechanisms required for you to automate this scenario. Most of those tools canned scenarios are designed around the simplest workflows that don't involve much complexity on the dependency front, but most have all the hooks you need to create your own workflows. Generally speaking, you're going to write some scripts, it's how they lock you in.
    – jwdonahue
    Commented Feb 22, 2018 at 19:43
  • 39
    Don't know why this answer was accepted, as it doesn't actually answer the original user's question.
    – Geuis
    Commented Aug 12, 2018 at 21:21
  • 1
    @Geuis, the question was "What is the common/best practice to adopt?", and I answered accordingly, to the best of my knowledge. Have you got a better answer in mind?
    – jwdonahue
    Commented Aug 13, 2018 at 20:50
  • @Geuis, I have updated the answer. Maybe I should have simply voted to close this thread, since it's asking more than one question? If not for the semantic-versioning tag, I would never have seen this thread. I've always been more focused on the SemVer standard, than how any of the various packaging tools implement it. Had @ShaharShokrani answered this question earlier, I would have simply moved on. Back then, I really had zero interest in NPM and I did not want to leave a SemVer thread unanswered.
    – jwdonahue
    Commented Jun 16, 2021 at 18:18
8

You can also remove and install the package.

npm rm package
npm i package
2
  • 1
    This answer needs more upvotes Commented Apr 5, 2022 at 16:33
  • 1
    you could also do npm i package@latest if the package is using the latest tag correctly
    – mDeram
    Commented Mar 5 at 13:08

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.