[DOCS] npm config: clarify unsupported custom user keys and document recommended alternatives #8843
Description
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
In npm 11.2.0, running commands like npm --version produces warnings about custom keys in .npmrc—for example, electron_mirror, electron_custom_dir, and electron_builder_binaries_mirror. These warnings state that these keys are unknown user config and will stop working in future npm versions. The docs do not explain why these custom keys are unsupported, or how users should configure package-level options without triggering npm warnings. Users rely on such keys for customizing mirror URLs and optimizing package downloads.
Current documentation appears unclear regarding:
- Which
.npmrckeys are officially supported or safe from future deprecation - How to properly separate user-level config from package-level config
- Whether there is a recommended alternative for setting custom parameters needed by third-party tools (like electron-builder) or for package management workflows
Potential Solution
Update the npm configuration documentation to clearly:
- List which
.npmrckeys are officially supported by npm and which will be rejected in future versions - Explain why custom user keys are not recognized and document their planned deprecation
- Provide explicit guidance for users who need to set custom config for third-party tools or package scripts — for example, alternative locations for these settings, or using package.json fields instead
- Link to discussions or issue comments (e.g. "Unknown user/project config" warnings starting in npm 11.2.0 #8153 (comment)) that provide best practices for package-level config
This would prevent future warnings and support a smoother migration for developers needing custom mirrors, especially for electron/electron-builder workflows.