utility package for loading, validating and documenting your app's configuration variables from env, json, jsonc and toml files at runtime and injecting them into your environment

Installation

defp deps do
  [
    {:enux, "~> 1.5"},

    # if you want to load `.jsonc` files, you should have this
    # you can also use this for `.json` files
    {:jsonc, "~> 0.9"},

    # if you want to load `.json` files, you should have either this
    {:euneus, "~> 1.2"}
    # or this
    {:jason, "~> 1.4"}
    # or this
    {:jaxon, "~> 2.0"}
    # or this
    {:json, "~> 1.4"}
    # or this
    {:jsone, "~> 1.8"}
    # or this
    {:jsonrs, "~> 0.3"}
    # or this
    {:poison, "~> 5.0"}
    # or this
    {:thoas, "~> 1.2"}
    # or use Erlang/OTP version 27 or higher

    # if you want to load `.toml` files, you should have either this
    {:tomerl, "~> 0.5"}
    # or this
    {:toml, "~> 0.7"}
  ]
end

Usage

In elixir 1.11, config/runtime.exs was introduced. This is a file that is executed exactly before your application starts. This is a proper place to load any configuration variables into your app. If this file does not exist in your project directory, create it and add these lines to it:

import Config
env = Enux.load()
config :otp_app, env

When you start your application, you can access your configuration variables using Applicatoin.get_env. If you need to url encode your configuration values, just pass url_encoded: true to Enux.load.

You should have either poison or jason or jaxon or thoas or jsone or json or jsonrs or euneus in your dependencies or use Erlang/OTP version 27 or higher if you want to use .json files. Priority is given to the dependencies, so if you want to use Erlang's own json module, don't add any of the mentioned packages.

To use .jsonc files, you should have jsonc. You can also use this package for .json files. To use .toml files, you should have either toml or tomerl or tomlex.

You can load multiple files of different kinds:

import Config

env1 = Enux.load("config/one.env", url_encoded: true)
config :otp_app, env1

env2 = Enux.load("config/two.json")
config :otp_app, :two, env2

automatic loading

Another way of using Enux is using the Enux.autoload function which will load all .env, .json, .jsonc and .toml files in your config directory. it makes more sense to call this function in your config/runtime.exs but you can call it anywhere in your code.

If you have config/pg.env and config/redis.json in your project directory, after calling Enux.autoload(:otp_app), you can access the variables using Application.get_env(:otp_app, :pg) and Application.get_env(:otp_app, :redis). if a file is named .env or .json or .jsonc or .toml, you should use Application.get_env(:otp_app, :env) or Application.get_env(:otp_app, :json) or Application.get_env(:otp_app, :jsonc) or Application.get_env(:otp_app, :toml) respectively.

Enux.autoload(:otp_app)

multiple environments

Using the MIX_ENV environmental variable you can adjust which files Enux.autoload loads into your app. If MIX_ENV is not specified, dev will be assumed. The only thing you need to do is specifying the environment in the name of each file like db-staging.env, redis-prod.jsonc or rabbitmq-unit-tests.toml. But after the file is loaded, you can access the variables using e.g. Application.get_env(:otp_app, :db) or Application.get_env(:otp_app, :redis) or Application.get_env(:otp_app, :rabbitmq). If a file doesn't have - in its name, Enux.autoload will load it regardless of the value of MIX_ENV.

environment validation

You may also use Enux.expect to both validate and document your required environment. first you need to define a schema:

schema = [
  id: [&is_integer/1, fn id -> id > 1000 end],
  username: [&is_binary/1, fn u -> String.length(u) > 8 end],
  metadata: [],
  profile: [
    full_name: [&is_binary/1],
    age: [&is_number/1]
  ]
]

then the following line will check for compliance of your environment under :otp_app and :key with the schema defined above (an empty list implies only checking for existence):

Enux.expect(:otp_app, :key, schema)