Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 39 ยท YAML and Config Files

Configuration Files: Layers, Env Vars and Formats

Learn how applications read configuration - choosing a format, .env and INI files, environment variables, deep merging and precedence from defaults to command-line flags - with runnable Node examples.

Almost every program has settings that should change without editing code: a database address, a port, a log level, a feature flag. Those settings live in configuration, and the format you pick (JSON, YAML, TOML, INI, .env, or code) shapes how pleasant the file is to write and how safely it is read. This lesson looks at the practical side: what formats exist, how several sources are layered on top of each other, and how to turn the strings you receive into typed values.

Which format for which job?

Format Comments Nesting Typical use
JSON no yes tool configs written by machines (package.json, tsconfig.json allows comments in its own dialect)
YAML yes yes CI pipelines, Kubernetes, Compose; see YAML Syntax Basics
TOML yes yes application settings, Python/Rust project files; see TOML in Depth
INI / properties yes one level (sections) older tools, Java .properties, PHP php.ini
.env yes no environment variables for one app or container
Code (config.js, Python module) yes any maximum flexibility, minimum safety

A good rule: use a data format for settings people edit, keep secrets out of files you commit, and prefer the format your ecosystem already uses.

.env files

A .env file is a list of NAME=value lines that a loader turns into environment variables for the process. There is no official standard, but the common rules are: one assignment per line, # starts a comment, values may be wrapped in single or double quotes, and the file is not committed when it contains secrets (commit a .env.example with fake values instead). Node 24 can even read such a file with process.loadEnvFile() or node --env-file=.env.

TEXT
# .env
PORT=3000
DATABASE_URL="postgres://user:pass@localhost:5432/shop"
DEBUG=false
Node.js Parse a .env file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice the last line of output: every environment variable is a string. DEBUG=false is the five-character text "false", which is truthy in JavaScript. Converting types is your job.

INI files

INI files group key=value pairs under [section] headers. They have no nesting beyond one level, no arrays and no types, and every dialect differs a little (comment markers ; or #, quoting rules, duplicate keys). They are fine for simple tools but TOML solves the same problem with a precise specification.

INI
; database settings
[database]
host = localhost
port = 5432

[cache]
enabled = yes

Layering: many sources, one result

Real applications combine several sources, from least to most specific:

  1. Defaults built into the code.
  2. A config file (shared or per environment: config.prod.yaml).
  3. Environment variables (set by the container, CI or shell).
  4. Command-line flags.

Later layers override earlier ones. This follows the twelve-factor idea that environment variables are the standard place to change behaviour per deployment, and flags are for one-off runs. Overriding is done with a deep merge: nested objects are merged key by key, while scalars and arrays are replaced.

flowchart LR
  D["defaults"] --> M["deep merge"]
  F["config file"] --> M
  E["environment"] --> M
  C["CLI flags"] --> M
  M --> V["validate + coerce types"] --> A["final config"]

Each layer overrides the previous ones; validation happens once at the end.

Node.js Layered configuration with deep merge and coercion

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The merge result still contains the strings "8080" and "false" from the environment; the coerce step is where they become a number and a boolean, and where bad values should be rejected. Doing this once, at startup, means the rest of the program works with trusted typed data.

Good practices

  • Fail fast. Validate the final configuration at startup and exit with a clear message naming the bad key, instead of crashing later.
  • Separate secrets. Passwords and tokens come from the environment or a secret manager, not from files in version control.
  • Document defaults. A commented example file (config.example.yaml) is the best documentation.
  • Keep one source of truth per setting. The more layers that can set a value, the harder it is to explain where it came from; log the effective configuration (without secrets) at startup.
  • Do not build config from untrusted input. Merging user-supplied objects without filtering keys like __proto__ leads to prototype pollution, see Data Format Security.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What type are values read from environment variables?

    Environment variables are plain text. DEBUG=false is the string "false", which you must convert yourself.
  2. 2. In a typical layered configuration, which layer has the highest priority?

    More specific and more temporary sources override more general ones, so flags beat environment variables, which beat the file, which beats the defaults.
  3. 3. What does a deep merge do with two nested objects that share a key?

    A deep merge recurses into objects, so a later layer can change one nested key without losing its siblings.
  4. 4. Why commit a .env.example instead of .env?

    The real .env often contains passwords and tokens. The example shows names and fake values.

Summary

  • Choose a data format for settings; keep secrets out of version control.
  • .env files are simple NAME=value lines; environment variables are always strings.
  • Layer configuration: defaults, file, environment, flags, with later layers winning via a deep merge.
  • Validate and convert types once at startup, and fail fast with clear messages.
  • Never merge untrusted keys blindly.

Next: TOML in Depth