Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 39 ยท Projects and Practice

Project: A Layered Configuration Loader

Build a complete configuration loader in Node - defaults, INI-style file, .env text, environment variables and command-line flags merged in order, validated against a schema, with provenance for every value.

In this project you assemble ideas from the whole course into one useful tool: a configuration loader like the ones inside real applications. It reads settings from five sources, merges them in priority order, converts text to typed values, validates the result against a schema, and can explain where each value came from. That last feature, provenance, is what makes configuration problems solvable at 2 a.m.

You will use: layered configuration, the INI dialect from INI, .properties and Other Plain-Text Formats, the .env rules, and the validation approach from Command-Line Data Tools. Everything runs in the sandbox: files are simulated with strings, and the environment and command-line arguments are passed in as plain objects, which also makes the loader easy to test.

Requirements

  1. Sources, from lowest to highest priority: defaults, config file (INI), .env file, environment variables (prefix APP_), command-line flags (--port=9000).
  2. Nested keys use dots in the file and double underscores in env vars (APP_DB__HOST is db.host).
  3. Values from text sources are converted by a schema: integer, boolean, string, with allowed ranges and enums.
  4. Missing required values and invalid values produce all errors at once, naming the key and the source.
  5. A explain() report shows each final value and its source.
flowchart LR
  D["defaults"] --> L["loader"]
  F["config.ini"] --> L
  E[".env"] --> L
  V["APP_* env vars"] --> L
  C["--flags"] --> L
  S["schema"] --> L
  L --> R["typed config + provenance + errors"]

Five sources plus a schema go in; typed values, their origins and a list of errors come out.

Step 1: parse each source into flat key -> string pairs

Flat maps with dotted keys are the common currency: every source is first reduced to {'db.host': 'localhost'}, which makes merging and provenance trivial. Nested structure is rebuilt at the very end.

Step 2: the whole loader

Node.js The configuration loader

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.

Study the output. The final configuration is a typed, nested object; explain() shows, for example, that port came from the environment and log.level from the command line; and the broken setup reports every problem at once, with the source that supplied the bad value, including the secret that was missing and a typo'd setting.

Design decisions worth noticing

  • Flat first, nested last. Merging dotted keys avoids a deep-merge function and makes provenance a simple second map.
  • The schema is the single source of truth: defaults, types, ranges, required keys, and which values are secret all live in one place.
  • Unknown keys are errors. A typo such as APP_COLOUR or db.hots should fail loudly, not be ignored.
  • Secrets are masked in reports and logs.
  • Pure function. The loader takes its inputs as arguments (env, argv, file text) instead of reading globals, so tests are one-liners. In production, wrap it: read files with node:fs, pass process.env and process.argv.slice(2).

Extensions to try

  1. Add a TOML or JSON file source (TOML in Depth has a parser you can reuse) and decide its priority.
  2. Add a list type: APP_ALLOWED_HOSTS=a.test,b.test becomes an array.
  3. Support ${VAR} references inside values, with a check against cycles.
  4. Print a config file template (--print-defaults) generated from the schema.
  5. Add deprecated: 'use db.host' to schema entries and warn when they are used.
  6. Freeze the result (Object.freeze recursively) so the rest of the program cannot mutate it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In the loader, which source has the highest priority?

    Layers are applied in order and later ones overwrite earlier ones; command-line flags are last.
  2. 2. Why are all sources first reduced to flat dotted keys?

    With flat maps, a later layer just overwrites a key, and a parallel map records where it came from.
  3. 3. Why does loadConfig take env and argv as parameters?

    Passing inputs explicitly means tests can supply any scenario without changing the real environment.
  4. 4. Why report all errors at once?

    Listing every issue with its source avoids a frustrating fix-one-restart-repeat cycle.

Summary

  • A good loader merges layered sources, converts text to typed values by schema, validates, and explains provenance.
  • Flat dotted keys keep merging simple; nested objects are rebuilt at the end.
  • Unknown keys and invalid values are errors; secrets are masked.
  • Pure functions with explicit inputs are easy to test.

Next: Project: A JSON Lines Log Analyser