How to override nested NPM dependency versions?

In projects the packages download and used using npm are called dependency and each dependencies can have their own nested dependencies that also gets downloaded. These nested dependency creates conflicts due to the presence of multiple version of the same dependency. This will lead to issues like compatibility, security vulnerabilities, and unexpected behavior.

To solve that we got multiple ways such as overrides property in package.json file, npm-force-resolutions, npm dedupe, npm-check-updates or yarn-upgrade-all.

Manual override in package.json

In the package.json file the overrides property can be used to add key value pair of dependency and its versions. The package name will be key and the value will be the version. Nesting of dependency as key is used for deeper nested dependency. After adding overrides property install or update the packages to apply the changes.

Syntax:

{
  "overrides": {
    "<dependency_name>": {
      "<nested_dependency_name>": "<exact_version_or_range>"
    }
  }
}

• dependency_name: It's the main dependency who's nested dependency you want to change.
• nested_dependency_name: This will be the name of the nested dependency that we want to target.
• exact_version_or_range: You can provide exact version or a range of version of the dependency to override.

Utilizing npm's npm-force-resolutions

You can install npm-force-resolutions package to force installation of a specific version of the dependency. Follow the steps to install and use this:

Step 1: Install npm-force-resolutions as a dev dependencies using the following command:

npm install npm-force-resolutions --save-dev

Step 2: Add resolutions to package.json with the dependency name and version that you want to change.

{
  "resolutions": {
    "<dependency_name>": "<version>" // Replace with the dependency and desired version
  }
}

Step 3: Add npm-force-resolutions to the preinstall script. This script runs npm-force-resolutions before every npm install command and modifies the package-lock.json file to reflect the forced version.

"scripts": {
  "preinstall": "npx npm-force-resolutions"
}

Step 4: Use the npm install command for installing the required dependency.

 npm install

Step 5: To verify the installation worked and the right version is installed run the following command.

npm ls <dependency_name>

Using npm dedupe(deduplicate)

The npm dedupe command used for analyzing and making the project's dependency tree much shorter by removing unnecessary copies of packages within your project's dependency tree. It searches for shared dependencies which are packages used by multiple packages in your project and then attempts to move them higher in the tree thus reducing disk space and improving efficiency in some cases.

You need not required to install anything as this dedupe is a native command of npm. Now the steps to use it is as follows:

Step 1: The terminal should be opened in your project root where package.json file is there. Use the cd command to navigate to the required directory.

 cd <path>

Step 2: Run npm dedupe to analyze your dependency tree and removing unnecessary copies of packages.

npm dedupe

Automation with npm-check-updates or yarn-upgrade-all

You also have npm-check-updates or yarn-upgrade-all commands that helps you to automate dependency updates, but they does not always handle nested dependency conflicts perfectly. Depending upon the package you are using you can automatically update all your project dependency to the latest versions.

npm users

Step 1: Use the following command to install the npm-check-updates package.

npm install -g npm-check-updates

Step 2: Use the the npm-check-updates or ncu command to check the list of possible updates.

ncu

Step 3: Use the u flag along with the ncu command to upgrade the version in the package.json file. This only changes the package.json file not install it.

ncu -u

Step 4: Install the required changes using the install command of npm.

 npm install

yarn users

Step 1: Install the yarn-upgrade-all package as a dev dependency using the following command.

yarn add --dev yarn-upgrade-all

Step 2: Now run the following command to update all the dependencies present in your package.json file.

yarn yarn-upgrade-all

Testing and documentation for changes

Testing

The various things to consider for testing the project for changes are:

• Backup: You must always create a complete project backup before overriding dependencies. This allows you to revert if necessary.
• Testing of specific dependency: Check the part of project that uses on the overridden dependencies.
• Version Checks: Make sure that the overridden versions are compatible with other project dependencies and your overall application requirements.
• Test in Different Environments: In Different environments such development or production, your project must be tested to catch any environment-specific issues.

Documentation

The various things to consider for documentation of the changes to the project and dependencies are:

• Document the Dependencies: Clearly document the overridden versions of nested dependencies and the reasoning behind it.
• Update every Information: Every time the package.json gets updated document the whole file by copying or copying only the specific changes.
• Document Testing Results: Record the results of your tests which can be any issues encountered after overriding dependencies or the project behaviours after the overrides.

Best practices for management

• Try for better Compatibility: Whenever possible try to choose dependency versions that work well together to minimize the need for overrides.
• Check for Security risks: If you dependencies or any nested dependencies have security vulnerability make sure you update or override it to a secure version.
• Use Exact Versions: For dependencies with lack of compatible version keep track and use an exact versions that works with other dependency so that you can avoid unexpected or breaking changes in future updates.
• Documentation: Try to document the working versions and changes made in the package.json file or any other file with respective to the dependency version. Also try to explain the reasons for overrides or other methods used for version changes.
• Automation is not perfect: If you are using automation tools like npm-check-updates or yarn-upgrade-all then carefully test you project after the automated updates as they might not always handle nested dependencies perfectly.