Have you ever had this situation that after upgrading some packages in your project some of its features, or in worst case whole project stopped working? I had this multiple time with node, but let me start with short story to illustrate the situation.Imagine you have a big node project and you noticed that some of you packages are outdated, or maybe they become vulnerable due to some lately discovered Node CVEs reported bugs. I think instinctively you would like to update all of the dependencies, so your project and yourself stay save and secure, right? But wait. After you hit npm run upgrade you notice it upgrades everything - literally all the packages. Cool! That is what you wanted, right? But wait again. In next quick step, (because now "quick" is always trendy) you rebuilding your project and during the compilation something isn't working properly. You also know the project is lacking of proper tests (integration/e2e). You remember very well there was always pressure of pushing new business feature further, and the tests was always like dead weight stopping you to complete you tickets in agile board before end of the sprint. Furthermore, at this place in time you cannot be sure if whole project works correct without literally manually test all places in your app which may take long, really long of your time. Next, you discover some dependencies changed, and few options pop up in your head:
some packages cannot be installed anymore,
or some packages become incompatible between versions,
or simply your project is not anymore working properly due to minor or major changes in SemVer,
or something else, but it's hard to say upfront without spending time on manual checking.
Is your case to some degree similar? If yes, then I'd encourage you to say and read further. I'll do all my best and trying to show you how you can secure the process of upgrading your dependencies with peace of mind.
What we need to know before starting?
We will show the process based on example with npm. If you work with node environment, you may encounter some opinions that npm can be really messy package manager, and there are some better alternatives. Some of this may be true, some may not - it's not me judging it here. So, if you're a huge fan of some other package managers, don't get so easily discouraged. I also have some my personal preferences, although here I'm just trying to show you the general solution how to solve the problem. I think the widespread popularity of npm is important here, and can be easily applied to alternative package managers. I could also bring the analogy with using different cars - it's not about the car's itself (I mean the brand you drive), it's about to moving from point A to point B.
Before upgrade it would be good if you have working and well-functioning test cases for your project (unit, integration, but best e2e), to make sure your business functionality is working fine both before and after upgrading to the new packages. Without tests it would be objectively very hard to say also with high confidentiality, that your project still working fine, or not.
How to begin upgrading your dependencies?
I imagine you have large node project, and you also following SemVer2 dependency schema. If so, that is great! This means, the expected changes in each type like: patch, minor or major also follow the agreed rules1. This is just dry theory, the real question is:
Well, node packages ecosystem, in some cases could be a complete mess. The SemVer there should be a standard to follow, although there are some amazing packages that prove it with great maintenance and transitions to new versions over the time. Although unfortunately, there are also some packages, which after some time, they may not well enough maintained, or updated properly, which may cause you troubles2.
There is no golden rule how to find reliable packages. Although I think there is few indicators, which without very deep knowledge can give us bit higher certainty in decision. Those are:
Popularity / Stars - will tell you if people recognize this package and endorse it. Technically the more the better.
Downloads per month - will tell you if the package is often used by regular downloads, or also indirectly by injecting it in the automated build processes. Technically the more the better.
Test coverage - this is the only known way to somehow proof the software behave according to its specification. If tests are implemented, that great indicator, and technically the more coverage the better. Although you have to know!: Tests are usually very stupid, as they follow the given specification. If test's specification is wrongly written, even if you have 100% of test coverage, this may give you nothing.
Vulnerability check - you can check it with few popular pages: Open Source Vulnerability Database or Snyk Security to get some indication how often the package get vulnerable and get patch. There is no standard rule for best practice but you could think of this as:
No reports could means package is old, not often used, or have perfect security (which I doubt)
Too much reports with low fixes could mean package is popular but in high risk area of usage
Too much reports with often fixes could mean package is popular but community care about it's good health
Process to upgrade all your dependencies
The process is very simple, but to do it right it require some time and carefully closing each stage in order. To make it bit easier, we will need to get some great npm package called ncu, in order to help us accomplish this task bit more easily. For now let's see the graph of process:
mermaid
graph TD A[Start: Patch Dependency Upgrade] --> B{Run Patch Tests}; B -- Pass --> C[Commit & Deploy Patch]; B -- Fail --> D[Fix & Re-test Patch]; D --> B; C --> E{Minor Dependency Upgrade?}; E -- Yes --> F{Run Minor Tests Load & E2E}; E -- No --> G{Major Dependency Upgrade?}; F -- Pass --> H[Commit & Deploy Minor]; F -- Fail --> I[Fix & Re-test Minor]; I --> F; H --> G; G -- Yes --> J{Run Major Tests Load & E2E}; G -- No --> K[End]; J -- Pass --> L[Commit & Deploy Major]; J -- Fail --> M[Fix & Re-test Major]; M --> J; L --> K; K[End];
You can install is globally for the whole system, or as dev-dependency for your project. The latter approach can additionally help your team to execute following upgrade commands out of the box, if you define them as tasks in the package.json file.
Next thing that would be important to check before begging the upgrades is to make audit and check which packages are in most dangerous state. For example, some may need critical update can wait. If you do not know what can happen search for CVE-2025-55182 and CVE-2025-66478 which were behind React2Shell critical vulnerability.
Perform regular audits
Doing some regular audits in larger projects is vital for the business. Ignoring this may cost a lot in various ways: loosing customer data, loosing critical data (digital products), or in the end the money as many serious actions may end up in court proceedings brought by the vitim/injured party.You can also party automate this process, at least to degree to inform you, or your team in audit reports finished after occasional checks.
Commands to upgrade node packages
Here is some example commands you may like to add into your package.json so it would be easier for you and your team to follow next upgrades.
jsonc
{ "scripts": { "upgrade:patch": "ncu --interactive --target patch", "upgrade:minor": "ncu --interactive --target minor", "upgrade:major": "ncu --interactive --target semver", // there is no major in API "upgrade:all-in-groups": "ncu --interactive --format group", },}
I've add 4 commands, 3 for each respective stage, which you could run separately one after another (one exception is major, as ncu doesn't have one). Although, technically you could run the last one upgrade:all-in-groups and execute it multiple times based and apply to given stage. As you can see in the picture below, it very nicely divide the upgrading for each of the stage. Plus, it shows the "Major version zero" (e.g.: v0.26.1), where anything may change. So pick the way you like.
In upcoming new sections, we will need to upgrade our packages in groups. One group after another, starting from patch, then moving to minor and finally end with major with possible breaking changes. After each minor and major upgrades, I would strongly encourage you to run full pipeline check (i.e: lint, test-unit, build, test-e2e) and if possible, also physically test if everything with application is ok. The level of physical testing (i.e.: how much and deep you should test) I will leave up to you, as each project is different and each stage may require various level of attention to testing (minor updates may require bit less testing, then major).
While upgrading, I find the most effective the following strategies:
lucky strike - Yes! Paradoxically, this is especially worth to try for patch or minor versions. Upgrading all from the respective group, and see if this works, may save yourself ton of time! If not, well, at least you know this will take a bit longer, and must use different strategy.
start with smaller and move to big players - if you see there are some small changes start with them. This fit great in as quick wins to reduce the list of upgrades. If you manage them move to important changes, e.g.: upgrades for framework, upgrade of the language (typescript). The big players except of the upgrade usually also require some manual change in the source code which also need to be done before run the checking if all works.
group respective upgrades in batches - for the things that make sense to join together. For example, if you see there are some updates for "eslint", and there are also few other packages related to "eslint", I would find it good to upgrade them in one batch, then test if works, and commit.
After each successful upgrade, save all changes in separate git commit. This may sounds obvious, but if you do granular upgrades it'll save you a thousands of problems and allow to progress until the end.
Commands to upgrade node packages
In the output above, let's take "eslint" as fist example package to upgrade. I would start with grouping following packages together: eslint, @eslint/js, @typescript-eslint/parser, eslint-plugin-prettier, typescript-eslint. Although it's critical to say, grouping by name does not guarantee success. There could be a situation where some grouping by name may have influence on other packages and different selection strategy need to be chosen.
If it's a patch update, it means it should provide some improvements without breaking the library/package/app. The minor may introduced some new changes, but generally it should not breaking existing business functionalities. Finally, the major upgrade may introduce breaking changes the current API or business functionality, which means it's most likely may require a more work to upgrade that package. ↩
I could not count how many times I wanted to upgrade some packages and my old entire work-tree has been broken. The recent situation I remember, was upgrading the eslint to flat structure. I had a project that has been using eslint with v8 with old structure and new upgrades in the framework encouraged to use v9, but in the end "forced" me to follow new conventions from eslint v9 as some thing stopped working. The problem was that project had lot of old dependencies and checkers for the rules this project had, which were not yet migrated to new flat structure. The result was simple to predict: a wall of errors during the build and frustration which library is failing and which is actually working fine. There was 2 ways how to proceed with it: not upgrade and make project vulnerable to security issues (which in node ecosystem are very common), or downgrade coding styles and remove some coding guidelines, which could reduce over the time the code unity in entire codebase and make it more difficult to maintain while working with many developers. ↩
