Nostalgic Pickled Mango

    TypeScript icon, indicating that this package has built-in type declarations

    0.6.3 • Public • Published


    NPM version Travis CI Coverage Status styled with prettier

    A lightweight/opinionated/versatile configuration module powered by yaml.


    Why the hell another Node.js config package?

    That's a question we asked ourselves before starting this module, we wanted simple config management with the following features:

    • Simple to use
    • Small footprint
    • Homogeneous config file format
    • No global/specific/pre-configured module to load (eg. require the lib, configure it and then require this file instead directly using the package)
    • Human readable
    • Concise
    • Comments
    • Types
    • Overrides
    • Env variables support

    Several modules already exist, but none of them matched our requirements, some were far too limited and others, in our opinion, really bloated.

    We chose yaml because it automatically covered several requirements, it's concise compared to json, you can add comments, it supports types and it's really easy to read it. Yaml also offers other neat features such as anchors.

    We only support yaml config files, having a project with json, xml, toml, ini, properties,… just does not scale when working on big projects, everyone adding its favorite flavor.

    Then we used environment variables to load overrides or define some specific keys, it makes really easy to tweak your config depending on the environment you're running on without touching a single line of code or even a config file. Really handy when using Docker heavily.

    We used this code across several projects (a small file comprised of ~100 loc at this time), and improved it when required.

    And here we are! It's now open source, and we hope it will help others building awesome things like it did for us.


    Using yarn

    yarn add @ekino/config

    Or npm

    npm install @ekino/config


    As this module heavily relies on environment variables, you could read this first if you're not comfortable with them.

    By default, this module assumes that configuration files are located in the root of your current working directory (process.cwd()). Yet, you can load files with relative path or absolute path anywhere else:

    ├─ conf/
       ├─ base.yaml        # the base configuration
       ├─ env_mapping.yaml # defines mapping between env vars and config keys
       └─ dev.yaml         # Optional file loaded if CONF_FILES includes `dev`

    base.yaml is required, it defines the common basic configuration of your application.

    Then to get a config key value in your code:

    # /conf/base.yaml
      key: xxxxx
    // test.js
    const config = require('@ekino/config')

    If we run this script, we'll have:

    node test.js
    > xxxxx

    Environment variables override

    Sometimes you want to override a single value on certain environments, to do so this module provides a special file called env_mapping.yaml, it allows to define per key override according to environment variable value.

    Assuming we've got the following config files:

    # /conf/base.yaml
      key: xxxxx
    # /conf/env_mapping.yaml
    HOST: host
    API_KEY: external_api.key

    And the following code:

    // test.js
    const config = require('@ekino/config')

    If we run this script, we'll have:

    node test.js
    > xxxxx API_KEY=12345 node test.js
    > 12345

    The second run outputs a different values because we mapped the HOST and API_KEY environment variables to the host and external_api.key config keys using env_mapping.yaml.

    Environment variables can be handy, however when reading them from node, we'll always get a string, this can be annoying when dealing with boolean values for example. That's why you can optionally force the type of the gathered environment variables value:

    # /conf/env_mapping.yaml
      key:  port
      type: number
      key:  use_ssl
      type: boolean

    For now we only support number and boolean types, if you think others could be useful, do not hesitate to contribute!

    CONF_FILES override

    If you've got a bunch of variations depending on the environment your're running your application on, it can be cumbersome to define tens of mappings inside the env_mapping.yaml file.

    This module gives you the ability to load overrides depending on the CONF_FILES environment variable value. Files in CONF_FILES are loaded in the same order they are defined, so for CONF_FILES=google,extra, it will load /conf/google.yaml, then /conf/extra.yaml. File path can either be relative (to the CONF_DIR director) or absolute.

    Let's say we've got those config files:

    # /conf/base.yaml
    service: awesome
    port:    8080
    # /conf/prod.yaml
    port: 8081
    # /conf/aws.yaml
    # /conf/google.yaml
    # /conf/extra.yaml
    port: 8082

    And the following code:

    // test.js
    const config = require('@ekino/config')

    If we run this script, we'll have:

    node test.js
    > awesome         # from base.yaml
    >  # from base.yaml
    > 8080            # from base.yaml
    CONF_FILES=prod node test.js
    > awesome         # from base.yaml
    >  # from prod.yaml
    > 8081            # from prod.yaml
    CONF_FILES=prod,aws node test.js
    > awesome             # from base.yaml
    >  # from aws.yaml
    > 8081                # from prod.yaml
    CONF_FILES=prod,google node test.js
    > awesome                # from base.yaml
    >  # from google.yaml
    > 8081                   # from prod.yaml
    CONF_FILES=prod,google,extra node test.js
    > awesome                # from base.yaml
    >  # from google.yaml
    > 8082                   # from extra.yaml

    ⚠️ The env_mapping.yaml will always take precedence over files overrides.

    Inheritance model

    base.yaml <— [<CONF_FILES>.yaml] <— [env_mapping.yaml]

    All files surrounded by [] are optional.

    1. Load config from <CONF_DIR>/base.yaml
    2. If CONF_FILES is defined, load each corresponding file if it exists
    3. If <CONF_DIR>/env_mapping.yaml exists and some environment variables match, override with those values




    npm i @ekino/config

    DownloadsWeekly Downloads






    Unpacked Size

    158 kB

    Total Files


    Last publish


    • ekino