Configuration
Choose which .env files load, mirror values back to process.env, and turn on debug logging.
envapt reads from 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.
. = ['.env.local', '.env'];
. = { : true };
. = true;
. = 'verbose';envapt loads .env files into an isolated copy of process.env, so by default it does not mutate the real
process.env. Values are read from envapt's own cache. syncProcessEnv (below) opts into writing them back.
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.
. = ['config/app.env', '.env'];Every path you list must exist. Setting envPaths validates the paths immediately, and a missing file throws
EnvaptError with code EnvFilesNotFound. Setting envPaths also takes precedence: it disables the
per-environment auto-cascade and any configureProfiles paths. Relative paths resolve against
process.cwd() unless you set Envapter.baseDir (below).
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.
. = { : true, : '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.
import { Envapter } from 'envapt';
// 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 lives only in envapt's cache. Set syncProcessEnv to mirror the keys envapt loaded back into process.env, so other libraries that read process.env directly see them.
. = 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.
Mirroring is one-way. Turning syncProcessEnv back to false does not remove keys already written; they stay in
process.env until the process exits.
Debug logging
debug controls how much envapt writes to stderr (prefixed [envapt]). The levels are silent (default), warn, and verbose.
. = 'verbose';warn: signals that may indicate misconfiguration: failed file reads, unresolved templates in non-strict mode, and fallback values used in place of a missing variable.verbose: adds every loaded file, per-file key counts, per-key load lines, effective paths, and cache rebuilds.
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