fix: improve unknown config warning with .npmrc section hint#8995
fix: improve unknown config warning with .npmrc section hint#8995wraithgar merged 4 commits intonpm:latestfrom
Conversation
Fixes npm#8153 When npm warns about unknown user/project/env config keys, the message now includes a hint about using [section] syntax in .npmrc for package-specific config (e.g. electron_mirror, sass_binary_site). The hint is omitted for --cli flags since they are unrelated to .npmrc.
| custom_dir={{ version }} | ||
| ``` | ||
|
|
||
| Section headers are ignored by npm's config loader, so they will not |
There was a problem hiding this comment.
This only works by accident and in the future we hope to have sections work for things like per-command config. As such this is not something we should be recommending in the npmrc file.
There was a problem hiding this comment.
Thanks for the feedback @wraithgar!
Understood — I'll remove the [section] recommendation.
Could you suggest what we should recommend instead?
Should users:
- Use environment variables (ELECTRON_MIRROR=...)
- Simply remove unknown keys from .npmrc
- Something else?
Happy to update the docs accordingly.
There was a problem hiding this comment.
The original version of this you submitted without the ini sections seemed fine to me, it covered the bases and felt like you'd read all of the other responses. config in package.json, environment variables, -- separation.
I don't believe there is a current analog to the config section in package.json for npmrc, and that is something we can look into going forward.
There was a problem hiding this comment.
@wraithgar Updated as per your feedback, removed the [section]
recommendation and the ini code block. Only kept the warning
explanation and environment variables approach. Let me know if
anything else needs changing!
There was a problem hiding this comment.
Sorry for nitpicking, but could you please update the PR description and also remove the sections recommendation there? I was a bit confused at first.
(By the way, I will miss this convenient config option.)
| You can set these values as environment variables instead: | ||
|
|
||
| ```bash | ||
| export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/" |
There was a problem hiding this comment.
In the past these example domains have been vectors for people to squat on them and claim a vulnerability. We try our best now to only use domains that npm itself owns, even in examples.
Can we change the example domains here to be something like mirrorexample.npmjs.org?
There was a problem hiding this comment.
@wraithgar Updated! Changed example domain to mirrorexample.npmjs.org
| exports[`test/lib/commands/config.js TAP config list with publishConfig local > warns about unknown config 1`] = ` | ||
| Array [ | ||
| "Unknown publishConfig config /"other/". This will stop working in the next major version of npm.", | ||
| "Unknown publishConfig config /"other/". This will stop working in the next major version of npm. To pass package-specific config, use a scoped [sectionName] in .npmrc. See \`npm help npmrc\`.", |
There was a problem hiding this comment.
Still recommending ini section here.
There was a problem hiding this comment.
@wraithgar Thanks for the feedback! Made all the changes:
- Removed the [sectionName] hint from the warning message
- Updated it to just say "See
npm help npmrcfor supported config options." - Removed the ini [section] recommendation from docs
- Fixed the example domain to mirrorexample.npmjs.org
- All tests and snapshots updated (108 suites passing)
Let me know if anything else needs tweaking!
|
I think this is ok to land, thanks for sticking with it. |
3 participants
Why / What
Fixes #8153
When npm 11.2.0 introduced unknown config key warnings, the message gave
users no actionable guidance:
Before:
Users were left confused — no hint on what to do instead.
After:
The hint is intentionally omitted for
--cliflag sources since CLIflags are unrelated to
.npmrcsyntax.Changes
workspaces/config/lib/index.js— Improved warning message incheckUnknown()with actionable.npmrcsection hintdocs/lib/content/configuring-npm/npmrc.md— Added "Custom /third-party config keys" section with migration examples
What was NOT changed
--flag) warnings unchanged — hint not applicable thereReferences
Fixes #8153