cacheDir env aliases (npm_config_cache_dir / NPM_CONFIG_CACHE_DIR) are silently ignored; only the .npmrc form works

[jdalton]

What happens

cacheDir can be set through a project .npmrc, and that works. The environment-variable forms of the same setting are accepted silently and have no effect.

Measured on released @nubjs/nub@0.6.0, one knob per container, one real nub add lodash each, counting files in the override directory and in the default cache afterwards:

How cacheDir was set	Override dir	~/.cache/nub/pm
npm_config_cache_dir=<dir> (env)	0 files	1056 files
NPM_CONFIG_CACHE_DIR=<dir> (env)	0 files	1056 files
cache-dir=<dir> in project .npmrc	1053 files	3 files
cacheDir=<dir> in project .npmrc	1053 files	3 files

So the setting is plainly wired up — the two .npmrc spellings both relocate the cache correctly. It is specifically the environment path that does not take.

Nothing is printed in the env cases: no warning, no "unknown setting", no note that the value was discarded. The install succeeds and writes to the default location.

Why this is worth more than a missing feature

Documented precedence is env above npmrc. Here the higher-precedence source is the one that does not work, which inverts the outcome rather than merely losing a knob:

Someone who sets npm_config_cache_dir=/fast/nub in CI and cache-dir=/project-local in .npmrc will get /project-local while reasonably believing the environment override won. Nothing in the output contradicts them. That is a harder failure to spot than the knob simply not existing, because the cache does move — just not to where they asked.

nub config list is consistent with the actual behaviour (it shows the .npmrc value and shows nothing for the env vars), so it does not mislead — but it also will not tell you your environment variable was dropped unless you already suspect it and go looking.

The general shape

This is the same class as a package manager accepting npm_config_store_dir and quietly doing nothing with it: the tool recognises the knob's name well enough to not complain, but does not honour it. A one-line warning when a recognised setting arrives on a source that is not consulted would turn a silent wrong-directory install into an obvious misconfiguration. That seems more valuable than the fix itself, since the same pattern can recur for any setting whose source list and read path drift apart.

Reproduction

docker run --rm node:26-slim bash -lc '
  npm install -g @nubjs/nub@0.6.0 >/dev/null 2>&1
  export HOME=/probe/home; mkdir -p $HOME
  export npm_config_advisory_check=off
  export npm_config_cache_dir=/probe/over/c ; mkdir -p /probe/over/c
  mkdir -p /tmp/p && cd /tmp/p && echo "{\"name\":\"t\",\"version\":\"1.0.0\"}" > package.json
  nub add lodash --allow-low-downloads >/dev/null 2>&1
  echo "override: $(find /probe/over/c -type f | wc -l) files"
  echo "default : $(find $HOME/.cache/nub/pm -type f | wc -l) files"
'

Prints override: 0 files / default: 1056 files. Swapping the env var for a .npmrc line containing cache-dir=/probe/over/c prints override: 1053 files / default: 3 files.

Expected

Either the environment aliases relocate the cache the way the .npmrc forms do, or nub warns that a recognised setting arrived on a source it does not read.

[pullfrog]

Reproduced on the current release. The fix is already on main, so the two disagree and both halves matter.

Release 0.6.0 — confirmed, and the cause is a presence check that only looks at .npmrc. From vendor/aube/crates/aube/src/commands/settings_context.rs at v0.6.0:

let npmrc = aube_registry::config::load_npmrc_entries(cwd);
let has_explicit = npmrc
    .iter()
    .any(|(k, _)| k == "cacheDir" || k == "cache-dir");
if !has_explicit {
    return platform_default();
}
with_settings_ctx(cwd, |ctx| { /* aube_settings::resolved::cache_dir(ctx) */ })

The settings table declares the aliases (sources.env = ["npm_config_cache_dir", "NPM_CONFIG_CACHE_DIR", "AUBE_CACHE_DIR"]) and the resolver honours them — the gate just returns before the chain ever runs. That is the drift you describe, and it costs more than the env forms: the CLI bag, pnpm-workspace.yaml, and aube-config.toml are equally unreachable for this one setting.

The gate also explains something the report doesn't cover: once any npmrc file names the key, the environment value is honoured and correctly outranks the file. One real nub add lodash per scenario, counting files under each candidate directory:

How cacheDir was set	Where the cache landed
npm_config_cache_dir (env only)	default
NPM_CONFIG_CACHE_DIR (env only)	default
project .npmrc cache-dir	override dir
env + project .npmrc, different dirs	env dir
env + user ~/.npmrc, different dirs	env dir

So precedence is right; only the entry gate is wrong. It is not a general env-family failure either: npm_config_store_dir and npm_config_node_linker both take effect from the environment alone (nub store path follows the first, the second hoists ms to the top of node_modules).

main (9e2eb69, built locally) — fixed. Both env spellings relocate the cache, and env still beats .npmrc. The gate was dropped by #621 (aube: sync upstream v1.35.0, 2026-07-29), four days after v0.6.0 shipped (2026-07-25), so the fix arrived incidentally with an engine sync and nothing pins the behaviour — no test covers env-set cacheDir at the resolved_cache_dir level. One regression test there would keep the next sync from taking it back out.

Two things are still open on main:

• NUB_CACHE_DIR does not move the PM cache. Same probe, cache stays at the default. It is one of the three sanctioned Nub env knobs and is documented in site/content/docs/install/index.mdx, but it is absent from the setting's sources.env list; only the resolver primer reads it, through config_env("CACHE_DIR") in aube-resolver/src/primer.rs. So after the main fix the documented knob is the one that still silently does nothing.
• The in-tree comments still describe the removed behaviour. pm_engine/mod.rs says the accessor "only consults the setting when .npmrc sets it explicitly" and points at an aube::set_cache_root registration that no longer exists; pm_engine/store_config_family.rs puts the cache at <XDG_CACHE_HOME>/aube/… when it is ~/.cache/nub/pm.

No duplicate exists. #643 is the same family on the other axis — a store-dir override honoured by some consumers and not others.

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using Claude Opus ｜ 𝕏}