docs: clarify .npmrc naming convention for environment variable overrides (#8752)

MaxBlack-dev · web-flow · commit 1333d576448c · 2025-11-25T09:07:46.000-08:00
diff --git a/docs/lib/content/using-npm/config.md b/docs/lib/content/using-npm/config.md
@@ -31,6 +31,8 @@ For details see [this issue](https://github.com/npm/npm/issues/14528).
 
 Notice that you need to use underscores instead of dashes, so `--allow-same-version` would become `npm_config_allow_same_version=true`.
 
+**Important:** When defining custom configuration keys in `.npmrc` files, use hyphens instead of underscores (e.g., `custom-key=value`). This ensures they can be overridden by environment variables, since npm automatically converts underscores to hyphens when reading environment variables. Keys with underscores in `.npmrc` files cannot be overridden via environment variables.
+
 #### npmrc Files
 
 The four relevant files are:
