"Unknown user/project config" warnings starting in npm 11.2.0

[pplmx]

---Added by npm team---

See this comment #8153 (comment) for the proper way to have package-level config that does not collide with npm config

Summary

When running npm --version, npm issues warnings about some custom configuration keys in my .npmrc. These warnings indicate that the keys will stop working in the next major version of npm.

Environment

• node version: v23.9.0
• npm version: 11.2.0
• Win11

Steps to Reproduce

1. Create a .npmrc file with the following content:

   registry="https://registry.npmmirror.com/"
   electron_mirror="https://npmmirror.com/mirrors/electron/"
   electron_custom_dir="{{ version }}"
   electron_builder_binaries_mirror="http://npmmirror.com/mirrors/electron-builder-binaries/"

2. Run the command:

   npm --version

3. Observe the following warnings:

   npm warn Unknown user config "electron_mirror". This will stop working in the next major version of npm.
   npm warn Unknown user config "electron_custom_dir". This will stop working in the next major version of npm.
   npm warn Unknown user config "electron_builder_binaries_mirror". This will stop working in the next major version of npm.

Expected Behavior
The custom configuration keys should be recognized, or there should be documentation clarifying the correct way to set these options without triggering warnings.

Actual Behavior
The custom keys (electron_mirror, electron_custom_dir, and electron_builder_binaries_mirror) are not recognized by npm, resulting in warning messages about their future deprecation.

Questions

1. Are these warnings expected with the current configuration, or is there a recommended way to define these custom options?
2. Will these configurations be supported in future versions of npm, or should they be modified/removed to ensure compatibility?

Additional Context
I am using custom mirror URLs to optimize package and binary downloads. Any guidance or documentation regarding the proper configuration for these settings would be greatly appreciated.

[timtucker-dte]

This also applies to things like NODE_OPTIONS and any options that are set for pnpm or other package managers that use .npmrc

[Medkhat]

• same

[spamshaker]

On my end:
npm warn Unknown user config "scripts.build". This will stop working in the next major version of npm.

[ljharb]

I believe the intention is to stop people from doing exactly that - from abusing npmrc as a way to define non-npm-related environment or configuration variables.

[nikolay-nenkov]

We have the same warnings with cli and env config:

npm run myScript --customVar

npm warn Unknown cli config "--customVar". This will stop working in the next major version of npm.

Will there be a way to whitelist some keys?

[ljharb]

My understanding is that only things npm uses will be supported. If you want to pass arguments to the script’s command itself, use -- to separate arguments npm consumes from ones the script’s command consumes.

[nikolay-nenkov]

That will pass arguments only to the last command in case the script is defined like:

"myScript": "command1 && command2"

Is there an easy way to pass parameters to both commands in this case?

[ljharb]

an environment variable, i suppose?

[jimmy-zhening-luo]

Why is this viewed as "abuse"? The 11.2.0 cli documentation clearly states that the config top-level object in package.json can be used to set configuration parameters, as in the example from the documentation:

A "config" object can be used to set configuration parameters used in package scripts that persist across upgrades. For instance, if a package had the following:

{
  "name": "foo",
  "config": {
    "port": "8080"
  }
}

It could also have a "start" command that referenced the npm_package_config_port environment variable.

@ljharb, your suggestion of a workaround, an environmental variable, is actually the exact case that has been broken without explanation.

@wraithgar, since you shipped this change, can you confirm if this is intended behavior? I think if npm is deprecating a top-level object in package.json, the above error messages are not a good (or clear) way to inform the user base.

[wraithgar]

The package.json#config example is exactly how you want to do this. Those aren't parsed as "npm" config values, those are isolated as "user space" config values for the package. Those are exported as npm_package_config_ and not npm_config so they are not something npm would try to re-parse as its own config.

~/D/s/glob $ npm pkg get config
{
  "foo": "hello world"
}
~/D/s/glob $ npm config ls|grep foo
~/D/s/glob $ npm run env|grep foo
npm_package_config_foo=hello world
~/D/s/glob $ npm -v 
11.2.0

No warnings.

[wraithgar]

This also applies to things like NODE_OPTIONS and any options that are set for pnpm or other package managers that use .npmrc

These should be unaffected. In .npmrc itself that config is node-options and npm sets that to NODE_OPTIONS in the environment.

[wraithgar]

I am going to pin this issue for now since there may be more folks who are wondering how to address these warnings. I also added a link to the OP to my comment about package.json#config since that's the solution we are recommending.