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 documentation here:
https://docs.npmjs.com/cli/v9/using-npm/config

Makes a mention that when using environment variables:

Notice that you need to use underscores instead of dashes, so --allow-same-version would become npm_config_allow_same_version=true.

Now pretty obviously to reverse map this, the NPM CLI will replace "_" with "-" when loading keys from env (i.e. "npm_config_some_thing" becomes "some-thing").

The problem now is that if you created a variable in the .npmrc file called "some_thing" it cannot be overridden by environment variables at all - which isn't obvious (especially since you'd normally access this as "process.env.npm_config_some_thing" and you'd be exporting an environment variable with the same name).

It seems like the docs could tell you the safest convention for naming variables in the .npmrc is to use hyphens, so that values can be overridden by env.

Potential Solution

Obviously this could be fixed in the code

Perhaps a double underscore is replaced with a single underscore and a single underscore is replaced with a hypen
e.g.
export npm_config_some__thing="hello" --> some_thing="hello"
export npm_config_some_thing="hello" --> some-thing="hello"

But the easier fix might be to add a paragraph to the docs:

"To make keys in the .npmrc file overridable by environment variables they should not contain underscores and should use hyphens instead"

Docs URL

https://docs.npmjs.com/cli/v9/using-npm/config