[DOCS] Please document "The overrides key will only be considered when it is in the root package.json file for a project"

[AlanSl]

Is there an existing issue for this?

• I have searched the existing issues

This is a CLI Docs Enhancement, not another kind of Docs Enhancement.

• This is a CLI Docs Enhancement.

Description of Problem

The public documentation for the overrides package.json key doesn't mention any limitations regarding workspaces or monorepos.

However, it seems overrides don't work in workspace package.json files (from my testing they only work from the root package.json), and this appears to be by design - the RFC says:

Only Root Package May Contain Overrides

The overrides key will only be considered when it is in the root package.json file for a project. overrides in installed dependencies (including workspaces) will not be considered in dependency tree resolution. Thus, there is no cascading overrides between multiple different package.json files at any given time.

Published packages may dictate their resolutions by pinning dependencies or using an npm-shrinkwrap.json file.

Applying overrides for workspaces and installed dependencies may be considered in a future RFC. However, there are considerable challenges in the implementation, user expectations, and security of such an approach.

Most package.json keys work in both root and workspace files, so this is a specific limitation of overrides that should be documented in the overrides docs.

I certainly expected overrides to work in workspaces as well as the project root based on having read the documentation, and I only discovered the RFC note after browsing recent overrides-related issues and finding #4205

Potential Solution

1. Add a line in the Overrides documentation saying something like:

In a monorepo with workspaces, overrides may only be defined in the project root package.json. Overrides within workspace package.json files are ignored.

2. Maybe also log a warning or error on running npm install if a workspace's package.json has an overrides key, rather than the feature just failing silently? Like:

Warning: overrides found in workspace ${workspaceName}. Overrides may only be set in the project root.

Docs URL

https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides

[nlf]

Add a line in the Overrides documentation saying something like:

this is a great idea, if you'd like you're welcome to submit a pull request adding this to the docs.

Maybe also log a warning or error on running npm install if a workspace's package.json has an overrides key, rather than the feature just failing silently? Like:

i like this idea a lot as well. i'm currently working on cleaning up some of the issues with overrides, and i'll keep this on my radar.

[maunzCache]

Finally a thread that explains my pains. The ERR! on npm install is not nearly enough to consider why this does not work.
A workaround btw is to run it with --force or --legacy-peer-deps which i would not recommend.

Edit: Maybe we need a follow-up on some linters as they consider the "overrides" keyword a valid one in this context, but i would be glad if they were aware of the workspace and would notify it when found in my package.json.