Fauda: configuration made simple

Nicolas Gryman — Wed, 25 Nov 2020 20:13:35 +0000

So, you finally wrapped up the core features of your new app / CLI tool. Great!

On with the configuration part...

Which file format to support? How to load these files? How to load env vars and CLI options as well? How to merge everything together? How to validate options and apply default values? Should Typescript be supported? Etc...

Chances are you have deadlines, so configuration might not be your top priority. As a consequence, you only have a limited time to address this. Even though you can find awesome libraries to help you implement each piece independently, you still need to figure out all the plumbing and handle every edge case. This could quickly become painful and time-consuming.

If this rings a bell, then you might be interested in Fauda!

It's an all-in-one library that:

loads options from multiple sources: env vars, CLI options, and configuration files.
merges them together in one unified configuration object.
normalizes it by validating against a JSON schema and setting default values.

It offers the following advantages:

Simple - a single dependency to load, merge, and validate your configuration.
Flexible - multiple file formats support out of the box such as JSON, YAML, JavaScript, and even Typescript!
Reliable - a unique source of truth defined in a JSON schema.
Typescript friendly - generated typings for your code and configuration files (bonus: auto-completion in VSCode). Take a look at https://github.com/ngryman/fauda for more info. Any feedback would be very much appreciated!

Getting Started

Let's assume you want to configure a server application with the following options:

port: The port the server listens to.
open: Open in a browser tab if true.
mode: Mode of the app.
publicPages: A list of public pages.

Install Fauda

npm install fauda

Set up your JSON schema

Fauda uses a JSON schema to load and normalize your configuration.

Create a schema.json file:

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "title": "My awesome app configuration",
  "type": "object",
  "properties": {
    "$schema": {
      "description": "Path to my app's schema.",
      "type": "string"
    },
    "port": {
      "description": "The port the server listens to.",
      "type": "number",
      "default": 3000
    },
    "open": {
      "description": "Open in a browser tab if true.",
      "type": "boolean",
      "default": false
    },
    "mode": {
      "description": "Mode of the app.",
      "type": "string",
      "enum": ["development", "production"],
      "default": "${NODE_ENV}"
    },
    "publicPages": {
      "description": "A list of public pages.",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": ["publicPages"]
}

For more information on JSON schemas, you can take a look at their Getting Started guide.

Generate types (optional)

Generating types allows you to have a strongly typed configuration object in your code. As a bonus, it also enables autocompletion for Typescript configuration files!

Generate a src/configuration.ts file:

$ npx fauda types

This will generate the following file:

export interface Configuration {
  port?: number
  open?: boolean
  mode?: 'development' | 'production'
  publicPages: string[]
}

For more information about generating types, please take a look at the README's CLI section.

Load & validate your configuration

Assuming your package's name is my-app:

import { fauda } from 'fauda'
import { Configuration } from './configuration'

async function loadConfiguration() {
  try {
    const configuration = await fauda<Configuration>('my-app')
  } catch (err) {
    console.error(err.message)
  }
}

That's all folks! 🎉

What's next?

You can take a look at Fauda's README, it's still in early development so any feedback will be much appreciated!