json_env

Environment Variable Loader

json_env is dotenv, but with JSON. It loads environment variables from JSON files (.env.json per default) and starts a subprocess with them. Storing configuration in the environment separate from code is based on The Twelve-Factor App methodology.

json_env is written in Rust, but a npm package is also provided, so you can also add it as a dev-dependency to your Node project.

Use-Cases

• Load different environment variables for different execution contexts (testing, staging, production)
• Load secrets (e.g. connection strings) from a dedicated configuration file
• Easily provide JSON values inside environment variables

How to install

With homebrew:

$ brew tap brodo/json_env
$ brew install json_env

With NPM

$ npm i -g @brodo/json_env

With cargo:

$ cargo install json_env

Or download the binaries for your platform on the releases page and put them in your $PATH.

How to use

Just run json_env with any program as a parameter:

$ json_env my_program

Additional command line arguments that are passed to json_env are forwarded to the child process:

$ json_env echo "Test"

Test

Example

.env.json:

{
    "NODE_ENV": "DEV",
    "MY_USER": "Carl",
    "NUM_USERS": 10,
    "nested": {
        "hello": "world",
        "boo": "far"
    }
}

Shell:

$ json_env env
MY_USER=Carl
NODE_ENV=DEV
NUM_USERS=10
nested={"boo":"far","hello":"world"}
[...]

json_env searches for .env.json files in the current directory and all parent directories.

Environment Variable Expansion

You can include existing environment variables in your env file to expand them:

.env.json:

{
  "MY_VAR": "$FOO",
  "MY_OTHER_VAR": "User:$USER"
}

Shell:

$ json_env -e env
FOO=Bar
MY_OTHER_VAR=User:Carl
MY_VAR=Bar
USER=Carl
[...]

JSON Path support

There are some use cases where you already have environment variables defined in a JSON file but not at the root level. Take this Azure Function local.settings.json file for example:

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "<language worker>",
    "AzureWebJobsStorage": "<connection-string>",
    "MyBindingConnection": "<binding-connection-string>",
    "AzureWebJobs.HttpExample.Disabled": "true"
  },
  "Host": {
    "LocalHttpPort": 7071,
    "CORS": "*",
    "CORSCredentials": false
  },
  "ConnectionStrings": {
    "SQLConnectionString": "<sqlclient-connection-string>"
  }
}

The Values property contains the environment variables we are interested in. You can use this file to run app.js with the environment variables defined in Values by providing the JSON Path .Values using the -p flag:

$ json_env -c local.settings.json -p .Values node app.js

Using multiple config files

In some cases, it makes sense to use several config files. For example, one file can be checked into your VCS containing default values and a second one can be used to overwrite some of them:

defaults.json

{
  "SERVER_URL": "https://example.com/foo",
  "USER": "TO_BE_OVERWRITTEN",
  "PASSWORD": "TO_BE_OVERWRITTEN"
}

my_settings.json

{
  "USER": "admin",
  "PASSWORD": "hunter2"
}

Use multiple -c flags to add several config files:

$ json_env -c defaults.json -c my_settings.json env
PASSWORD=hunter2
SERVER_URL=https://example.com/foo
USER=admin
[...]

Later config files overwrite the earlier ones. You can also use multiple JSON paths, which are applied in order.

License

json_env is licensed under the Apache 2.0 license.