fix: improve unknown config warning with .npmrc section hint

docs/lib/content/configuring-npm/npmrc.md

@@ -124,6 +124,33 @@ _authToken=MYTOKEN
 //somewhere-else.com/another/:_authToken=MYTOKEN2
 ```
 
+### Custom / third-party config keys
+
+npm only recognizes its own [configuration options](/using-npm/config).
+If your `.npmrc` contains keys that are not part of npm's config definitions
+(for example, `electron_mirror` or `sass_binary_site`), npm will emit a
+warning:
+
+```
+warn Unknown user config "electron_mirror".
+This will stop working in the next major version of npm.
+```
+
+These keys were historically tolerated but are not officially supported.
+A future major version of npm will treat unknown top-level keys as errors.
+
+Some tools (such as `@electron/get` or `node-sass`) read their own
+configuration from environment variables or from `.npmrc` by convention.
+You can set these values as environment variables instead:
+
+```bash
+export ELECTRON_MIRROR="https://mirrorexample.npmjs.org/mirrors/electron/"
+export ELECTRON_CUSTOM_DIR="{{ version }}"
+```
+
+Environment variables are the most portable approach and work regardless
+of `.npmrc` format.
+
 ### See also
 
 * [npm folders](/configuring-npm/folders)

tap-snapshots/test/lib/commands/config.js.test.cjs

@@ -451,6 +451,6 @@ registry = "https://some.registry"
 
 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. See \`npm help npmrc\` for supported config options.",
 ]
 `

test/lib/commands/publish.js

@@ -55,7 +55,7 @@ t.test('respects publishConfig.registry, runs appropriate scripts', async t => {
   t.equal(fs.existsSync(path.join(prefix, 'scripts-prepublish')), false, 'did not run prepublish')
   t.equal(fs.existsSync(path.join(prefix, 'scripts-publish')), true, 'ran publish')
   t.equal(fs.existsSync(path.join(prefix, 'scripts-postpublish')), true, 'ran postpublish')
-  t.same(logs.warn, ['Unknown publishConfig config "other". This will stop working in the next major version of npm.'])
+  t.same(logs.warn, ['Unknown publishConfig config "other". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.'])
 })
 
 t.test('re-loads publishConfig.registry if added during script process', async t => {

test/lib/commands/unpublish.js

@@ -409,7 +409,7 @@ t.test('publishConfig no spec', async t => {
   t.equal(joinedOutput(), '- test-package')
   t.same(logs.warn, [
     'using --force Recommended protections disabled.',
-    '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. See `npm help npmrc` for supported config options.',
   ])
 })
 

workspaces/config/lib/index.js

@@ -608,13 +608,16 @@ class Config {
       if (internalEnv.includes(key)) {
         return
       }
+      const hint = where !== 'cli'
+        ? ' See `npm help npmrc` for supported config options.'
+        : ''
       if (!key.includes(':')) {
-        this.queueWarning(key, `Unknown ${where} config "${where === 'cli' ? '--' : ''}${key}". This will stop working in the next major version of npm.`)
+        this.queueWarning(key, `Unknown ${where} config "${where === 'cli' ? '--' : ''}${key}". This will stop working in the next major version of npm.${hint}`)
         return
       }
       const baseKey = key.split(':').pop()
       if (!this.definitions[baseKey] && !this.nerfDarts.includes(baseKey)) {
-        this.queueWarning(baseKey, `Unknown ${where} config "${baseKey}" (${key}). This will stop working in the next major version of npm.`)
+        this.queueWarning(baseKey, `Unknown ${where} config "${baseKey}" (${key}). This will stop working in the next major version of npm.${hint}`)
       }
     }
   }

workspaces/config/test/index.js

@@ -381,8 +381,8 @@ loglevel = yolo
     // warn logs are emitted as a side effect of validate
     config.validate()
     t.strictSame(logs.filter(l => l[0] === 'warn'), [
-      ['warn', 'Unknown builtin config "builtin-config". This will stop working in the next major version of npm.'],
-      ['warn', 'Unknown builtin config "foo". This will stop working in the next major version of npm.'],
+      ['warn', 'Unknown builtin config "builtin-config". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.'],
+      ['warn', 'Unknown builtin config "foo". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.'],
       ['warn', 'invalid config', 'registry="hello"', 'set in command line options'],
       ['warn', 'invalid config', 'Must be', 'full url with "http://"'],
       ['warn', 'invalid config', 'proxy="hello"', 'set in command line options'],
@@ -399,13 +399,13 @@ loglevel = yolo
       ['warn', 'invalid config', 'prefix=true', 'set in command line options'],
       ['warn', 'invalid config', 'Must be', 'valid filesystem path'],
       ['warn', 'config', 'also', 'Please use --include=dev instead.'],
-      ['warn', 'Unknown env config "foo". This will stop working in the next major version of npm.'],
-      ['warn', 'Unknown project config "project-config". This will stop working in the next major version of npm.'],
-      ['warn', 'Unknown project config "foo". This will stop working in the next major version of npm.'],
-      ['warn', 'Unknown user config "user-config-from-builtin". This will stop working in the next major version of npm.'],
-      ['warn', 'Unknown user config "foo". This will stop working in the next major version of npm.'],
-      ['warn', 'Unknown global config "global-config". This will stop working in the next major version of npm.'],
-      ['warn', 'Unknown global config "foo". This will stop working in the next major version of npm.'],
+      ['warn', 'Unknown env config "foo". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.'],
+      ['warn', 'Unknown project config "project-config". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.'],
+      ['warn', 'Unknown project config "foo". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.'],
+      ['warn', 'Unknown user config "user-config-from-builtin". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.'],
+      ['warn', 'Unknown user config "foo". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.'],
+      ['warn', 'Unknown global config "global-config". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.'],
+      ['warn', 'Unknown global config "foo". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.'],
       ['warn', 'invalid config', 'loglevel="yolo"', `set in ${resolve(path, 'project/.npmrc')}`],
       ['warn', 'invalid config', 'Must be one of:',
         ['silent', 'error', 'warn', 'notice', 'http', 'info', 'verbose', 'silly'].join(', '),
@@ -600,12 +600,12 @@ loglevel = yolo
       ['warn', 'invalid config', 'prefix=true', 'set in command line options'],
       ['warn', 'invalid config', 'Must be', 'valid filesystem path'],
       ['warn', 'config', 'also', 'Please use --include=dev instead.'],
-      ['warn', 'Unknown env config "foo". This will stop working in the next major version of npm.'],
-      ['warn', 'Unknown user config "default-user-config-in-home". This will stop working in the next major version of npm.'],
-      ['warn', 'Unknown user config "foo". This will stop working in the next major version of npm.'],
-      ['warn', 'Unknown global config "global-config". This will stop working in the next major version of npm.'],
-      ['warn', 'Unknown global config "foo". This will stop working in the next major version of npm.'],
-      ['warn', 'Unknown global config "asdf". This will stop working in the next major version of npm.'],
+      ['warn', 'Unknown env config "foo". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.'],
+      ['warn', 'Unknown user config "default-user-config-in-home". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.'],
+      ['warn', 'Unknown user config "foo". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.'],
+      ['warn', 'Unknown global config "global-config". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.'],
+      ['warn', 'Unknown global config "foo". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.'],
+      ['warn', 'Unknown global config "asdf". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.'],
     ])
     logs.length = 0
   })