Features • Getting Started • How does it work? • Usage • API • CLI • FAQ

Fauda is an all-in-one library that:

1. loads options from multiple sources: env vars, CLI options, and configuration files.
2. merges them together in one unified configuration object.
3. 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).

npm install fauda

{
  "$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"]
}

$ npx fauda types

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

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)
  }
}

Fauda loads your configuration from several sources using the following order of precedence: environment variables > CLI options > configuration files.

Option names are inflected according the source's typical naming convention:

Once your configuration is loaded, Fauda normalizes it into a valid configuration object that your library / application can use. The normalization process validates your configuration using the provided JSON schema. It checks that the type of options are valid, required options are specified, sets default values, and also expand environment variables references!

"mode": {
  "default": "${NODE_ENV}"
}

"mode": {
  "description": "Mode of the app.",
  "type": "string",
  "enum": ["development", "production"],
  "default": "${NODE_ENV}"
}

Fauda first searches for a config.${myApp} property in the package.json file of your users. If not found, it then searches for a various configuration files, starting from the current directory up to the root.

Here is a list of the configuration file names and formats that are supported:

Fauda parses CLI options as you can expect from any other argument parsers!

Options are "kebab-"cased. For instance, the publicPages option is transposed as the --public-pages CLI argument.

$ my-app --public-pages=/home --public-pages=/about
$ my-app --types="['/home', '/about']"

Fauda parses environment variables prefixed with your package's name. This is precaution to avoid name clashes with other application or system-wide environment variables.

For instance, if your package's name is my-app, Fauda will parse variables with the MY_APP_ prefix.

$ MY_APP_PUBLIC_PAGES="['/home', '/about']"

Loads, normalizes, and returns a configuration object from multiple sources.

Params

• namespace string: String used to prefix environment variables and namespace your configuration in the package.json. It's typically your package's name.
• schema string | JsonObject: Path to a JSON schema, or the schema itself, used to normalize your configuration.
• options? Partial<FaudaOptions>: See available options.

Examples

import { fauda } from 'fauda'

const configuration = await fauda('my-app', 'schema.json')

Normalizes a configuration object using the provided JSON schema.

Params

• config: JsonObject: Configuration object to normalize.
• schema: string | JsonObject: Path to a JSON schema, or the schema itself.
• env?: NodeJS.ProcessEnv: (default: process.env) An object containing environment variables, used to expand variables in the schema.

Examples

import { normalize } from 'fauda'

const schema = {
  type: 'object',
  properties: {
    foo: {
      type: 'string',
      default: 'bar'
    }
  }
}

const safeConfig = await normalize({}, 'schema.json')
// { foo: 'bar' }

Returns the Configuration type definition inferred from the given JSON schema.

Params

• schema string | JsonObject: Path to a JSON schema, or the schema itself, used to generate the Configuration type.
• options? Partial<Options>: See available options of json-schema-to-typescript.

Examples

import { promises as fs } from 'fs'
import { generateTypes } from 'fauda'

const source = await generateTypes('schema.json')
await fs.writeFile('src/configuration.ts', source)

Fauda comes with a CLI utility that automatically generates types from your JSON schema. This is especially useful to provide a strongly typed configuration object to your Typescript project, but also to provide auto-completion for your users using a .ts configuration file.

By default, the types command will read a schema.json file and write the output to a src/configuration.ts file:

You can change these defaults with the following CLI options:

• --input, -i: Path to a JSON schema file.
• --output, -o: Path to the output Typescript file.

Examples

$ fauda types
$ fauda types -i my-schema.json -o src/types/configuration.ts

{
  "scripts": {
    "build": "tsc",
    "prebuild": "fauda types"
  }
}

{
  "scripts": {
    "dev": "run-s dev:*",
    "dev:types": "fauda types",
    "dev:build": "tsc -w"
  }
}

Fauda only supports a flat options object, simply because it's easier to manipulate and to reason about. In my opinion, nested options are usually neither a good idea as it makes merging default options harder, nor necessary as one can express a sense of hierarchy using "dotted names" instead (eg. cooking.time) or just camel case (eg. cookingTime).