@bedrockio/config

Install

npm install @bedrockio/config

Philosophy

Config is loaded when you require this package, not when you launch the process. That is a deliberate choice over Node's native --env-file flags.

--env-file only applies to the one process invocation that remembers to pass it. That splits how a project loads env into two triggers: some files load automatically (whatever a config library reads on import) and some load only when the right flag was on the command line. The failure mode is quiet — a "naked" node script.js still gets base defaults, so it looks like it worked, but silently misses every override the flags would have layered on. Node has also declined to auto-load .env by default, so the per-invocation flag overhead is not going away.

Loading the whole cascade here, on require, removes the split. Every entry point — the server, a worker, a one-off script — resolves config the same way with no flags to remember.

File cascade

Files are merged in order, later files winning:

1. .env — base defaults, committed.
2. .env.${ENV_NAME} — per-environment overrides (e.g. .env.production), committed. ENV_NAME is read from the shell, or from the base .env if the shell does not set it.
3. .env.local — machine-local overrides, gitignored, always wins.

A real process.env value still wins over every file, so ENV_NAME=production node ... both selects the environment and takes precedence. Override files are optional siblings of the base file — with none present, loading is identical to reading .env alone.

All values are loaded into process.env, which is the single source of truth: get/has read from it, and third-party libraries that read process.env directly (Sentry, cloud SDKs, and so on) see your config too. Declaring a key in any file makes it present in the environment; an empty declaration is stored as an empty string, so an override can blank out a base value with KEY=.

Usage

Create a .env file in the root directory of your project. Add environment-specific variables on new lines in the form of NAME=VALUE. For example:

DB_HOST=localhost
DB_PORT=2000
SENTRY_API=
START_DATE=2019-01-30T10:00:48.185Z

const config = require('@bedrockio/config');
db.connect({
  host: config.get('DB_HOST'),
  port: config.get('DB_PORT', 'number'),
});

// check if START_DATE is bigger than current time and SENTRY_API has value
if (config.get('START_DATE', 'date') < Date.now() && config.has('SENTRY_API')) {
  sentry.init({
    dsn: config.get('SENTRY_API'),
  });
}

Methods

get

Default: config.get('DB_HOST', "string"): string

Return the value of the variable or throws an error if the variable is not defined in the .env or available via process.env.

config.get(
  variable,
  as?: "string" | "boolean" | "json" | "number" | "date"
): string | number | boolean | Date | any

has

Default: config.has('DB_HOST'): boolean

Returns true if the variable is present in process.env (an empty declaration counts as present).

getAll

Default: config.getAll(): {[key: string]: string}

Return all keys declared in your env files as a key/value object, read from process.env. The ambient environment (PATH, etc.) is not included.

getPublic

Default: config.getPublic(): {[key: string]: string}

Like getAll, but only the declared keys whose name starts with a public prefix (APP_ or PUBLIC_ by default, configurable via the ENV_PUBLIC_PREFIXES environment variable, comma separated).

Environment variable ENV_CONFIG_PATH

This variable allows you set a different location for your .env file.