@justsml/auto-config

Intro

A Unified Config & Arguments Library for Node.js!

Featuring support for environment variables, command line arguments, and (soon) JSON/YAML/INI files!

Why

There are so many config libraries, do we really need another??? Well, possibly!

No existing library I tried met my requirements.

My goals & requirements include:

• Enable dynamic app config. See '12 Factor App' on Config
• TypeScript support.
• Portable pattern (not filesystem-locked, browser support.)
• Simple, memorable & terse config format.

Table of Contents

• Intro
• Why
• Example
  • Configuring your App Dynamically
    • Command line arguments
    • Mix of environment and command arguments
    • Single-letter flag arguments
    • Error on required fields
    • --help CLI Output
  • TODO
  • Credit and References

Install

npm install @justsml/auto-config

yarn add @justsml/auto-config

Example

// `./src/config.ts`
import { autoConfig } from '@justsml/auto-config';

export default autoConfig({
  databaseUrl: {
    help: 'The Postgres connection string.',
    args: ['--databaseUrl', '--db', 'DATABASE_URL'],
    required: true,
  },
  port: {
    help: 'The port to start server on.',
    args: ['--port', '-p', 'PORT'],
    type: 'number',
    required: true,
  },
  debugMode: {
    help: 'Debug mode.',
    args: ['--debug', '-D'],
    type: 'boolean',
    default: false,
  },
});

// `./src/app.js`
import config from './config';
console.log(config);

Configuring your App Dynamically

Command line arguments

node ./src/app.js \
  --port 8080 \
  --databaseUrl 'postgres://localhost/postgres' \
  --debug
# { port: 8080, databaseUrl: 'postgres://localhost/postgres', debug: true }

Mix of environment and command arguments

DATABASE_URL=postgres://localhost/postgres \
  node ./src/app.js \
    --port 8080 \
    --debug
# { port: 8080, databaseUrl: 'postgres://localhost/postgres', debug: true }

Single-letter flag arguments

node ./src/app.js \
  -D \
  --port 8080 \
  --databaseUrl 'postgres://localhost/postgres'
# { port: 8080, databaseUrl: 'postgres://localhost/postgres', debug: true }

Error on required fields

node ./src/app.js \
  --port 8080
# Error: databaseUrl is required.

CLI Help Output

node ./src/app.js --help

╭───────────────────────────┬────────────────────────────────────────────┬──────────────────────────────────────────────────────────╮
│                           │                                            │                                                          │
│  Name                     │  Help                                      │  CLI Args, Env Name(s)                                   │
│                           │                                            │                                                          │
├───────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────────────────────┤
│databaseUrl*               │The Postgres connection string.             │--databaseUrl, DATABASE_URI, DATABASE_URL                 │
├───────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────────────────────┤
│port*                      │The port to serve content from.             │-p, --port                                                │
├───────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────────────────────┤
│[debugMode] = false        │Debug mode.                                 │-D, --debug                                               │
├───────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────────────────────┤
│help                       │Show this help.                             │--help                                                    │
├───────────────────────────┼────────────────────────────────────────────┼──────────────────────────────────────────────────────────┤
│version                    │Show the current version.                   │--version                                                 │
╰───────────────────────────┴────────────────────────────────────────────┴──────────────────────────────────────────────────────────╯

TODO

• [ ] Enum support.
• [ ] Inverting boolean flags with --no-debug versus --debug.
• [x] Auto --help output.
• [x] --version output.
• [x] default values.
• [x] required values.
• [x] Zod validators for optional, min, max, gt, gte, lt, lte.

Credit and References

Projects researched, with any notes on why it wasn't a good fit.

• yargs - like the fluent API, and command syntax. Could use as base library. Env vars could be handled via default helper function to check for env keys. Or we could transform yargs config into overlapping format.
• commander - like the many ways to configure arguments. Could probably be used as underlying library, however initial attempt was slower than starting from scratch.
• cosmiconfig - focused too much on disk-backed config.
• rc - focused on 'magically' locating disk-backed config.
• node-convict - great pattern, but limited TypeScript support.
• nconf - setter & getter, plus the hierarchy adds extra layers.
• conf - too opinionated (writing to disk.) Interesting use of JSON Schemas, Versioning, and Migrations.
• gluegun - great design, focused on opinionated design of CLI apps though.
• configstore - replaced by conf.