Identify and fix bundle npm duplicate dependencies

Modern web applications are becoming more complex, and they rely on an increasing number of dependencies. The larger the dependency tree is, the more likely it is to encounter version conflicts, bundle duplicate dependencies, ship unnecessary code, and negatively impact user performance.

On the front-end side, modern web applications include in the bundle a median of 98 direct and transitive dependencies1, 108% growth in the last three years.

Why the bundle contains duplicate dependencies

When a package is depended upon by multiple other dependencies and/or the application, npm resolves the dependency tree, and if a common version does not satisfy all the semver queries, it installs multiple instances of the same package. By installing multiple instances of the same dependency, npm meets the dependent package.json and avoids breaking existing functionality.

If the duplicate package is a front-end dependency, it is bundled multiple times, increasing the size of the bundle, negatively impacting the application's web performance and, in some cases, causing Javascript runtime errors (ex: Duplicate React).

Resources:

Example

For example, in an application that depends on @ant-design/icons@4.7.0 (resolved to v4.7.0) and antd@4.24.14, npm installs two different instances of @ant-design/icons because antd@4.24.14 depends on @ant-design/icons@^4.7.0 (resolved to v4.8.1):

"package.json"
{
"name": "example-app",
// ... package information
"dependencies": {
"@ant-design": "4.7.0",
"antd": "4.24.14"
}
}

npm list @ant-design/icons
example-fix-npm-dependencies@1.0.0 repo
├── @ant-design/icons@4.7.0
└─┬ antd@4.24.14
└── @ant-design/icons@4.8.1

As a result, the bundle includes two versions of the same dependency:

Bundle analysis - duplicate packages

Identify duplicate dependencies

RelativeCI analyzes the bundle stats modules data, extracts the list of bundled dependencies, and identifies duplicate dependency instances. The information is presented as custom insights, metrics, and a list that you can filter and sort to discover the regressions quickly.

Duplicate packages insight

The duplicate packages insight shows the status and the result of the duplicate packages analysis, allowing you to easily identify when there are regressions(new duplicate instances) or improvements (removed duplicates). The insight information is available on the bundle analysis report summary, job list, and all the integration summaries.

Bundle analysis - duplicate packages insight
Bundle analysis - duplicate packages insight

Bundle analysis list - duplicate packages insight
Bundle analysis list - duplicate packages insight

GitHub Pull Request Comment - Duplicate packages insight
GitHub Pull Request Comment - Duplicate packages insight

Duplicate packages metric

The number of duplicate packages is available as a distinct metric on the report summary, the job list, and all the integration summaries.

Bundle analysis summary - duplicate packages metric
Bundle analysis summary - duplicate packages metric

Bundle analysis list - duplicate packages metric
Bundle analysis list - duplicate packages metric

Also, you can use the metric as a condition on the GitHub Commit Status Review or the Slack notification.

Bundle analysis review flow
Bundle analysis review flow

Duplicate packages data

To see the list of duplicate packages, go to the Packages section of the bundle analysis report and filter the results by the Duplicate filter. This will give you an overview of all the duplicate dependencies and their impact on the bundle size.

Bundle analysis - packages

Fix npm duplicate dependencies

The strategies for resolving npm duplicate dependencies may vary depending on your setup, dependencies, and versions. However, the following methods can help you eliminate duplicate packages, reduce bundle size, and enhance your application's web performance.

npm dedupe

npm dedupe can help to quickly fix any existing issues in the package-lock.json file by flattening the dependency tree and regenerating the package-lock.json.

For example, the app dependency depends on @ant-design/icons@^4.6.0 and the correct semver resolution should be 4.8.1, though the package-lock.json resolves to 4.6.0:

npm explain @ant-design/icons
@ant-design/icons@4.6.0
node_modules/@ant-design/icons
@ant-design/icons@"^4.6.0" from the root project
@ant-design/icons@4.8.1
node_modules/antd/node_modules/@ant-design/icons
@ant-design/icons@"^4.7.0" from antd@4.24.14
node_modules/antd
antd@"^4.18.6" from the root projects

Running npm dedupe will correct the package-lock.json and remove the duplicate dependency:

npm dedupe
npm list @ant-design/icons
example-fix-npm-dependencies@1.0.0 repo
├── @ant-design/icons@4.8.1
└─┬ antd@4.24.14
└── @ant-design/icons@4.8.1 deduped

Bundle analysis - duplicate packages - fixed using npm dedupe

Upgrade/downgrade to a common version

Update and/or downgrade the dependency to a common version that the dependents can share.

In the example above, we can update the application version to v4.8.1, the same as the version resolved for antd. npm will resolve both dependencies to v4.8.1

Updating a package version, especially major versions, can break existing functionality. Follow the change log of the dependency for changes and make sure to test after the update.

npm install --save @ant-design/icons@^4.8.1
example-fix-npm-dependencies@1.0.0 repo
├── @ant-design/icons@4.8.1
└─┬ antd@4.24.14
└── @ant-design/icons@4.8.1 deduped

Npm overrides

npm overrides configuration allows to explicitly set package versions and override the npm resolution for any dependency, direct or transitive.

In our example, we can override the resolved version of @ant-design/icons to 4.7.0.

Updating a package version, especially major versions, can break existing functionality. Follow the change log of the dependency for changes and make sure to test after the update.

package.json
{
"name": "app",
/* ... */
"dependencies": {
"@ant-design/icons": "^4.6.0",
"antd": "^4.18.6",
/* ... */
},
"overrides": {
"antd": {
"@ant-design/icons": "4.7.0"
}
}
}

npm list @ant-design/icons
example-fix-npm-dependencies@1.0.0 /Users/vio/work/relative-ci/examples/fix-npm-duplicates
├── @ant-design/icons@4.7.0
└─┬ antd@4.24.14
└── @ant-design/icons@4.7.0 deduped

Webpack configuration

Webpack allows dependency imports to be overridden at bundle time using resolve.alias configuration option.

Updating a package version, especially major versions, can break existing functionality. Follow the change log of the dependency for changes and make sure to test after the update.

To point all the app imports of @ant-design/icons to the same version, we can add an entry to resolve.alias:

webpack.config.js
module.exports = {
// ... webpack config
resolve: {
alias: {
'@ant-design/icons': path.join(__dirname, 'node_modules/@ant-design/icons'),
}
}
};

[1]: Data based on open-source projects analyzed by RelativeCI

2020202120222023
Median package count47529598
Mean package count4676130138

Need help?Contact us via email, Twitter, or GitHub!

Start analyzing and monitoring yourbundle stats