Env Key Precedence Verdict

Decide which definition of an environment variable your process will ACTUALLY use. Pure function: no I/O, no environment reads, no dependency on dotenv -- and it never accepts a secret.

Measured against dotenv 17.x on Node 26. Not affiliated with or endorsed by the dotenv project.

THE SILENT FAILURE, MEASURED:

  process.env before   "from_shell"
  result.parsed        {"MYKEY":"from_dotenv_file"}   <- the FILE's value
  process.env after    "from_shell"                   <- what the app actually uses
  reported error       none. config() reported success.

THREE THINGS ARE TRUE AT ONCE, and together they cost an afternoon. The file is correct -- reading it confirms your change is there. The loader says it succeeded -- nothing raised, nothing warned. And result.parsed CONTAINS YOUR NEW VALUE even though it was never applied.

That third one is the trap. The obvious way to debug this -- print what dotenv parsed -- shows exactly the value you just typed and CONFIRMS THE WRONG CONCLUSION. The only place the truth is visible is process.env, which is the one thing nobody checks, because they believe they just set it.

This is the mechanism behind "I put my API key in .env and it is still using the old one."

{ override: true } fixes it. The default is override:false, SO THE DEFAULT IS THE FAILING CASE.

WHY THE VARIABLE IS SO OFTEN ALREADY SET. Rarely because anyone typed export. The usual causes are invisible from inside the project: a shell rc that ran when the terminal opened, a launchd or systemd unit, docker run -e, a CI secret, a parent process, a secret-manager shim -- or an editor launched from Spotlight or Dock, which inherits a DIFFERENT environment from your terminal. That last one is why "it works in my terminal but not in the editor" is so common and so rarely diagnosed: they are two different environments, and only one has the variable.

IT NEVER ASKS FOR YOUR KEY. The Source type has no field that accepts a value -- only where a name is DEFINED, plus an optional fingerprint YOU compute. A tool that asks for your API key in order to tell you your API key is misconfigured has made the problem worse. There is a test pinning this, so adding a value field for convenience fails the suite and has to be argued for in review.

IT REFUSES RATHER THAN GUESSING. If the loader's override behaviour is unknown and more than one source exists, the verdict is UNDECIDABLE -- not an assumed winner. dotenv's default IS override:false, but that is a default, not a fact about your project, and a confident wrong answer here sends you to edit the file that is being ignored. MISSING likewise says the variable is not defined by any source that was CHECKED -- never proof of absence, since a parent process can define it without appearing in any file.

STATED IN THE LIBRARY'S FAVOUR, because a listing that only reports what a library gets wrong is not being honest about it: recent dotenv prints a decorative line reporting how many variables it injected -- "injected env (1)" versus "injected env (0)". That count IS the signal and it is genuinely there. It also sits on a tip line beside an advertisement, is easy to scroll past, and is absent or unread in most non-interactive logs.

VERIFIED: 17 tests, measured by running the suite. The reproduction script ships in evidence/ and regenerates every number above against your own dotenv version.

DELIVERY: free, signed download of a hash-verified tarball, immediately. Full source, no card, no trial, no expiry.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function evaluatePrecedence(input: PrecedenceInput): PrecedenceVerdict;

  export type Severity = "critical" | "warning" | "note";