"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

[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.

[ljharb]

@Rudxain npm comes with node and shouldn't be installed separately, and node in the debian repos is broken - if you must use apt, use the nodesource repos.

As for that warning, do you have a ~/.npmrc, or any environment variables that case-insensitively start with NPM_CONFIG_?

[hyrious]

/cc @deepak1556 as VS Code uses .npmrc to store some custom configurations which might be affected.

$ npm -v
npm warn Unknown project config "disturl". This will stop working in the next major version of npm.
npm warn Unknown project config "target". This will stop working in the next major version of npm.
npm warn Unknown project config "ms_build_id". This will stop working in the next major version of npm.
npm warn Unknown project config "runtime". This will stop working in the next major version of npm.
npm warn Unknown project config "build_from_source". This will stop working in the next major version of npm.
npm warn Unknown project config "timeout". This will stop working in the next major version of npm.
11.2.0

If it is actually not you can ignore this comment.

---

Summary of this issue list: The ideal way would be using package.json#config and replace custom env named npm_config_xxx with npm_package_config_xxx.

[Rudxain]

After installing Node&NPM via NVM, the warning is gone. I'll hide my comments

[Tom4U]

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.

But this seems to be static, isn't it?!
I'm having the same issue, because I provide --myArg=myValue to some of my NPM scripts. Setting this value static in package.json is therefore no option. I still need to parse this dynamic information to my NPM scripts.

[wraithgar]

-- has always been the way to separate npm args and script args.

~/D/s/scripts $ npm pkg get scripts.argtest
"node ./script.js"
~/D/s/scripts $ npm run argtest -- hello

> [email protected] argtest
> node ./script.js hello

process.argv.slice(2): [ 'hello' ]
~/D/s/scripts $ cat script.js 
console.log('process.argv.slice(2):', process.argv.slice(2));

[malice00]

I am getting this error for some configurations that I thought belong to NPM:

npm warn Unknown user config "disturl". This will stop working in the next major version of npm.
npm warn Unknown user config "always-auth". This will stop working in the next major version of npm.
npm warn Unknown user config "email". This will stop working in the next major version of npm.

Besides that, what should I do for configurations that are computer-specific or settings that are needed for all projects? We have the above and some other settings in $HOME/.npmrc on our CI-Servers to retrieve everything from our inhouse mirrors, which we don't do when we are working from home / building in the cloud (eg EXPO).

[wraithgar]

Reminder to please read the ---Added by npm team--- section at the very top of this issue for how to set configs in a way that does not collide w/ npm config.

[malice00]

That does absolutely NOT resolve my issue! I am asking about settings that are NOT package-level, but system-level!

I don't want to add these configurations to all my package.jsons and have to switch them out when I am running my installs on other machines.

[alexsch01]

Reminder to please read the ---Added by npm team--- section at the very top of this issue for how to set configs in a way that does not collide w/ npm config.

Ok that works as a local project's .npmrc replacement, but it doesn't work as a global .npmrc replacement

[Tom4U]

I guess I have to clarify my use case here and I cannot see any solution to this.

Here's how I use custom arguments in one of my NPM scripts:

"serve": "nx run-many -t serve --projects=%npm_config_project%-ui,%npm_config_project%-api"

Running it like npm run serve --project=app1

As you can see, it's NX workspace, running commands dynamically. As it's a monorepo, I want to avoid to create all my required NPM scripts per project for all my projects I have inside it. This would lead to some huge project.json.

Using environment variables is no option, because running with env var like PROJECT=app1 npm run serve is not cross-platform compatible. Also (as far as I know) env vars are still not accessible inside package.json for NPM scripts.

So what do maintainers recommend for such use cases?

[ljharb]

cross-env PROJECT=app1 npm run serve works fine on all platforms, and env vars have always been accessible inside npm scripts.