Configuration

On Node, Bun, and Deno the default source reads process.env plus the .env files it loads. Static settings on Envapter control which files load, whether loaded values reach process.env, and how much envapt logs. They apply only while a Node source is active, on Workers and in the browser you bind a source instead.

Envapter.envPaths = ['.env.local', '.env'];
Envapter.envFileOptions = { override: true };
Envapter.syncProcessEnv = true;
Envapter.debug = 'verbose';

Which files load

By default envapt loads .env, and in a detected environment it layers a per-environment cascade (covered in Environment).

Set envPaths to load a fixed, ordered list instead. Earlier paths win.

Envapter.envPaths = ['config/app.env', '.env'];

envFileOptions tunes how files are read. override (default false) decides whether a later file or a file value can replace an already-set key; encoding (default utf8) sets the file encoding.

Envapter.envFileOptions = { override: true, encoding: 'utf8' };

Reading from a fixed directory

Relative paths resolve against the working directory (process.cwd()) by default. In a monorepo the process often starts at the repository root, not the package directory, so a package-local .env is not found. Set Envapter.baseDir to the directory that relative paths resolve against: the auto-cascade, configureProfiles paths, and relative envPaths. Absolute paths are used unchanged.

// ESM: resolve .env next to this module, whatever the working directory is
Envapter.baseDir = import.meta.url;

// CommonJS
Envapter.baseDir = __dirname;

baseDir accepts a directory path, a module URL (import.meta.url), or import.meta.dirname / __dirname. Set it before envPaths so relative envPaths validate against the same directory. Leave it unset to keep process.cwd() resolution.

Mirroring to process.env

By default a loaded value stays in envapt's cache. Set syncProcessEnv to mirror the keys envapt loaded back into process.env, so other libraries that read process.env directly get them.

Envapter.syncProcessEnv = true;

Only keys envapt's loader wrote are mirrored, so collisions follow envFileOptions.override: with the default false, a pre-existing process.env value is preserved.

Mirrored values are resolved first, so ${VAR} templates are expanded before they reach process.env and match what Envapter.get returns.

Debug logging

debug controls how much envapt writes to stderr (prefixed [envapt]). The levels are silent (default), warn, and verbose.

Envapter.debug = 'verbose';

• warn: signals that may indicate misconfiguration: failed file reads, unresolved templates in non-strict mode, and any read of a missing or empty variable, or under strict mode a whitespace-only one (whether it returns a fallback or undefined).
• verbose: adds the base directory, every loaded file, per-file key counts, per-key load lines, effective paths, cache rebuilds, and any present value a built-in converter could not parse (a malformed value that fell back to its default).

You can also set the level without code through the ENVAPT_DEBUG environment variable. envapt reads it on first access; an explicit Envapter.debug assignment overrides it.

ENVAPT_DEBUG=verbose