Configuring npm
How NES packages install with npm, how to check and upgrade your npm version, and how to fix the two install problems we see most often.
npm is the default package manager for Node.js. It fetches the packages your project depends on and installs them in node_modules. You list those dependencies, along with the version or version range you need, in your project's package.json file.
For supported Node.js and npm versions, see Minimum Requirements.
How NES packages replace Open Source packages
Replacing Open Source packages with NES packages, without changing your application code, takes two steps.
- Install each NES package in place of its Open Source equivalent, under the same name. Protocol aliases (
npm:) do this. An alias installs the NES package in the samenode_modulesdirectory where your application looks for the Open Source one. - Force every direct and transitive dependency that depends on the Open Source package to use the NES package instead. Overrides do this. An override replaces every copy of a package in your tree, including copies that other packages ask for, with the version you set.
Every NES install page for npm includes an overrides block for this reason.
npm added overrides in version 8.3.0. Older versions ignore the block without a warning, so the install succeeds but can leave Open Source copies in your project. Verify your install shows what that looks like and how to check for it.
Check and upgrade npm
Run node -v and npm -v to see what you have. The npm version is the one that matters here. Keep in mind that the npm version that comes bundled with the Node.js release you use isn't always new enough.
| Node.js release | Ships with | What to do |
|---|---|---|
| 12.13 - 12.22 | npm 6 | Run npm install -g npm@8 |
| 14.15 - 14.21 | npm 6 | Run npm install -g npm@8 |
| 16.0 - 16.13 | npm 7.10 - 8.1 | Run npm install -g npm@8 |
| 16.14 - 16.20 | npm 8.3 or newer | Nothing |
| 18 and later | npm 8.6 or newer | Nothing |
After upgrading, npm -v should report 8.3.0 or newer.
npm 8 runs on Node.js 12.13 or newer in the 12 line, 14.15 or newer in the 14 line, and Node.js 16 or newer. On any other Node.js release, upgrade Node.js first.
Verify your install
A successful install doesn't prove every copy was replaced. This example project uses NES jQuery and DataTables, an Open Source library that depends on jQuery itself. The example uses trial package versions.
{
"name": "my-app",
"version": "1.0.0",
"dependencies": {
"jquery": "npm:@neverendingsupport/jquery@2.2.5-trial",
"datatables.net": "1.13.11"
},
"overrides": {
"jquery": {
".": "npm:@neverendingsupport/jquery@2.2.5-trial"
}
}
}
After you install, run npm ls for each Open Source package that you are replacing with an NES one. With npm 8.3 or newer, every copy of jQuery is the NES version.
$ npm ls jquery
my-app@1.0.0 /path/to/my-app
├─┬ datatables.net@1.13.11
│ └── jquery@npm:@neverendingsupport/jquery@2.2.5-trial deduped
└── jquery@npm:@neverendingsupport/jquery@2.2.5-trial overridden
A line marked deduped points to the same NES copy, and overridden means the overrides entry was applied. Older npm versions may not print overridden.
If you remove the overrides block, or install the same project with npm 8.2 or earlier, DataTables gets its own Open Source copy.
$ npm ls jquery
my-app@1.0.0 /path/to/my-app
├─┬ datatables.net@1.13.11
│ └── jquery@4.0.0
└── jquery@npm:@neverendingsupport/jquery@2.2.5-trial
The jquery@4.0.0 line is the Open Source package. To fix it, check that you're on npm 8.3 or newer and that your overrides block has an entry for jquery, then reinstall.
Only check the Open Source packages that you are replacing with NES ones.
Common issues
Fix ERESOLVE peer dependency errors
This is a common error when switching to NES packages. The following example project shows why it happens and how to fix it.
This example project uses NES AngularJS and AngularJS Slider, an Open Source library that declares a peer dependency on angular. It has no overrides block.
{
"name": "my-app",
"version": "1.0.0",
"dependencies": {
"angular": "npm:@neverendingsupport/angularjs@1.8.3-trial",
"angularjs-slider": "7.1.0"
}
}
On npm 7 and later, npm install stops with this error.
npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: my-app@1.0.0
npm ERR! Found: angular@1.8.3-trial
npm ERR! node_modules/angular
npm ERR! angular@"npm:@neverendingsupport/angularjs@1.8.3-trial" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer angular@"^1.2.x" from angularjs-slider@7.1.0
This error doesn't mean AngularJS Slider is incompatible with NES AngularJS. npm rejects the NES version because of how it reads the version number. NES version numbers contain a hyphen, such as 1.8.3-trial, and npm treats any version with a hyphen as a prerelease. When npm checks a peer dependency range, a prerelease only matches a range that names a prerelease of the same version. So ^1.2.x never matches the NES version, even though 1.8.3 is within that range.
To fix it, add an overrides entry for the package named after Found:, in this case angular. The product's install page includes this entry, so copying its full overrides block fixes the error.
{
"name": "my-app",
"version": "1.0.0",
"dependencies": {
"angular": "npm:@neverendingsupport/angularjs@1.8.3-trial",
"angularjs-slider": "7.1.0"
},
"overrides": {
"angular": {
".": "npm:@neverendingsupport/angularjs@1.8.3-trial"
}
}
}
With that entry in place, npm uses the NES version everywhere and doesn't run the range check. Keep an entry for every NES package you install, even one you don't think anything else depends on.
If you can't override the package across your whole tree, override it only for the package that reports the error.
"overrides": {
"angularjs-slider": {
"angular": "npm:@neverendingsupport/angularjs@1.8.3-trial"
}
}
Use the same version as the angular entry in your dependencies.
Don't use --force or --legacy-peer-deps to get past this error. They let the install finish without fixing the missing override, and they also hide real peer dependency conflicts.