What does npm install –legacy-peer-deps do exactly? When is it recommended / What’s a potential use case?

by

TL;DR:

You may be arriving upon this answer if you’re upgrading from NPM v6 / Node v12.

  • NPM v7+ installs peerDependencies by default; this is not the case with previous versions of NPM.
  • NPM modules must name specific versions of their peerDependencies
  • If you already have a peerDependency installed, but not with a version named by the module, then NPM v7+ will throw an error
  • Adding --legacy-peer-deps ignores this new requirement, at the risk of introducing breaking changes

–legacy-peer-deps restores peerDependency installation behavior from NPM v4 thru v6

One way of thinking of this flag is that it isn’t doing something new; rather it’s telling NPM not to do something new, since NPM v7 now installs peerDependencies by default.

In many cases, this is leading to version conflicts, which will break the installation process.

The --legacy-peer-deps flag was introduced with v7 as a way to bypass peerDependency auto-installation; it tells NPM to ignore peer deps and proceed with the installation anyway. This is how things used to be with NPM v4 thru v6.

If you’re unclear about the difference between regular deps and peer deps, here is a bit of context:

Dependencies vs peerDependencies

Dependencies: Libraries or modules that an NPM module needs in order to work in production. (Example: I recently built a pie chart mocking library that uses Chance.js to calculate random numbers within a specified range; Chance is therefore a dependency of my module.)

peerDependencies: A peer dependency is a specific version or set of versions of a third-party software library that a module is designed to work with. They’re similar in concept to the relationship between a browser extension and a browser. (Example: react-redux has two quite logical peerDependencies: react and redux.)

This issue is being driven, in part, by React v17

Due to the large number of modules that haven’t specifically added React v17 as a peerDependency, it’s now commonplace to encounter the unable to resolve dependency tree error when running npm installs within a v17 React application.

This error will fire whenever a module (or any of its own dependencies) lists a previous version of React as a peerDependency without specifically including React v17 as well.

(Note: Similar behavior will occur with the major-version update of any other framework or library.)

How to check peerDependencies for any given module

NPM itself doesn’t list peer deps on the pages of a given module. However, there is a simple workaround to check for peer deps, either before or after install. Simply run:

npm info name-of-module peerDependencies

This command will return the name of each peerDependency along with all compatible version(s).

More Related Contents:

  1. npm – EPERM: operation not permitted on Windows
  2. Installing a local module using npm?
  3. How to use npm modules in browser? is possible to use them even in local (PC)?
  4. How do I completely uninstall Node.js, and reinstall from beginning (Mac OS X)
  5. Node.js – SyntaxError: Unexpected token import
  6. “SyntaxError: Unexpected token < in JSON at position 0"
  7. Sending command line arguments to npm script
  8. Uncaught Error: Invariant Violation: Element type is invalid: expected a string (for built-in components) or a class/function but got: object
  9. Is it safe to store a JWT in localStorage with ReactJS?
  10. Difference between npx and npm?
  11. How do we or can we use node modules via npm with Meteor?
  12. Module not found: Error: Can’t resolve ‘crypto’
  13. Running NPM scripts sequentially
  14. ‘Access-Control-Allow-Origin’ issue when API call made from React (Isomorphic app)
  15. Appending .js extension on relative import statements during Typescript compilation (ES6 modules)
  16. How to use npm module in DENO?
  17. `npm build` doesn’t run the script named “build” in package.json
  18. Angular 2 – How to pass URL parameters?
  19. How to publish a module written in ES6 to NPM?
  20. ‘react-scripts’ is not recognized as an internal or external command
  21. useEffect does not listen for localStorage
  22. How do you import a javascript package from a cdn/script tag in React?
  23. Fix the upstream dependency conflict installing NPM packages
  24. unable to deploy next js to azure
  25. create-react-app: How do I “npm start” with a specific browser?
  26. Module build failed (from ./node_modules/babel-loader/lib/index.js): Error: Cannot find module ‘babel-preset-react’
  27. JavaScript dependency management: npm vs. bower vs. volo [closed]
  28. Access from origin ‘https://example.com’ has been blocked even though I’ve allowed https://example.com/
  29. Firebase-Admin, importing it to react application throws Module not found error
  30. Want to have an event handler for the browser’s back button with next.js

Leave a Comment