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

Differentiating Dependencies: Comrades and Peers

Peer dependencies are special; they're the comrades who work side-by-side with your package in the trenches of your project, unlike regular dependencies which are the backbone of your package.

When the grumpy npm v7 started to automatically install these comrades alongside your package, developers started worrying about unexpected incompatibilities popping up. So --legacy-peer-deps became the magic wand to skip this hardhead and get back to the good old days.

Legacy flag: To Use or Not to Use

• React Misfit: If you're a frontend alchemist trying to work with React and those rebel modules who refuse to acknowledge React v17 as a peer space cadet, this might be your shot.
• Dependence Dispute: Upgrading packages leading to sibling rivalries that make the Jerry Springer show look mild? Use it!
• Old Soldier's Tale: Dealing with ye olde projects that partly run on fossil fuel? Keep with the times, but gingerly.
• Strict Taskmaster: Must your project's version dependencies be as disciplined and specific as a marching band? Updating might break their formation, so consider this.

Identifying the Culprit: Troubleshooting

• npm's X-ray Goggles: npm info is detective Holmes at your service. It helps you understand the partner preferences of your package.
• Setting Controls: .npmrc can become your cruise control. Just set legacy-peer-deps=true and relax.
• Brute Force: --force is the Hulk mode. It's more aggressive than --legacy-peer-deps. Not recommended unless you're okay with things potentially going haywire.

Break free from Peer pressure: Other ways

Chalk out your path

In projects with incompatible peer dependencies, you can add a "resolutions" field in your package.json, a map guiding npm to the safest path.

Yarn to your rescue

Yarn does a graceful ballet around these peer dependency conflicts, unlike the npm bulldozer. It’s worth a shot.

The Omission tactic

Another manoeuvre is --omit=peer. This orders a package’s dependencies without their peers hence granting you the leadership.

Your npm: Personalized

npm Preferences set right

To make npm remember your liking for the legacy behaviour rather than asking you every time, run: npm config set legacy-peer-deps true.

Regular Cleanup

A regular run around your project with npm outdated and npm update in tow cleans up your project, reducing messy situations where --legacy-peer-deps is your only savior.