@ryniaubenpm2/saepe-corporis-ullam

Dotenv-expand adds variable expansion on top of dotenv. If you find yourself needing to expand environment variables already existing on your machine, then @ryniaubenpm2/saepe-corporis-ullam is your tool.

Install

1# Install locally (recommended)
2npm install @ryniaubenpm2/saepe-corporis-ullam --save

Or installing with yarn? yarn add @ryniaubenpm2/saepe-corporis-ullam

Usage

Create a .env file in the root of your project:

1PASSWORD="s1mpl3"
2DB_PASS=$PASSWORD

As early as possible in your application, import and configure dotenv and then expand dotenv:

1const dotenv = require('dotenv')
2const dotenvExpand = require('@ryniaubenpm2/saepe-corporis-ullam')
3
4dotenvExpand.expand(dotenv.config())
5
6console.log(process.env) // remove this after you've confirmed it is expanding

That's it. process.env now has the expanded keys and values you defined in your .env file.

dotenvExpand.expand(dotenv.config())

...

connectdb(process.env.DB_PASS)

Preload

Note: Consider using dotenvx instead of preloading. I am now doing (and recommending) so.

It serves the same purpose (you do not need to require and load dotenv), has built-in expansion support, adds better debugging, and works with ANY language, framework, or platform. – motdotla

You can use the --require (-r) command line option to preload dotenv & @ryniaubenpm2/saepe-corporis-ullam. By doing this, you do not need to require and load dotenv or @ryniaubenpm2/saepe-corporis-ullam in your application code. This is the preferred approach when using import instead of require.

1$ node -r @ryniaubenpm2/saepe-corporis-ullam/config your_script.js

The configuration options below are supported as command line arguments in the format dotenv_config_<option>=value

1$ node -r @ryniaubenpm2/saepe-corporis-ullam/config your_script.js dotenv_config_path=/custom/path/to/your/env/vars

Additionally, you can use environment variables to set configuration options. Command line arguments will precede these.

1$ DOTENV_CONFIG_<OPTION>=value node -r @ryniaubenpm2/saepe-corporis-ullam/config your_script.js

1$ DOTENV_CONFIG_ENCODING=latin1 node -r @ryniaubenpm2/saepe-corporis-ullam/config your_script.js dotenv_config_path=/custom/path/to/.env

Examples

See tests/.env.test for simple and complex examples of variable expansion in your .env file.

Documentation

@ryniaubenpm2/saepe-corporis-ullam exposes one function:

• expand

Expand

expand will expand your environment variables.

1const env = {
2  parsed: {
3    BASIC: 'basic',
4    BASIC_EXPAND: '${BASIC}',
5    BASIC_EXPAND_SIMPLE: '$BASIC'
6  }
7}
8
9console.log(dotenvExpand.expand(env))

Options

processEnv

Default: process.env

Specify an object to write your secrets to. Defaults to process.env environment variables.

1const myEnv = {}
2const env = {
3  processEnv: myEnv,
4  parsed: {
5    HELLO: 'World'
6  }
7}
8dotenvExpand.expand(env)
9
10console.log(myEnv.HELLO) // World
11console.log(process.env.HELLO) // undefined

FAQ

What rules does the expansion engine follow?

The expansion engine roughly has the following rules:

• $KEY will expand any env with the name KEY
• ${KEY} will expand any env with the name KEY
• \$KEY will escape the $KEY rather than expand
• ${KEY:-default} will first attempt to expand any env with the name KEY. If not one, then it will return default
• ${KEY-default} will first attempt to expand any env with the name KEY. If not one, then it will return default

You can see a full list of rules here.

How can I avoid expanding pre-existing envs (already in my process.env, for example pas$word)?

Modify your dotenv.config to write to an empty object and pass that to dotenvExpand.processEnv.

1const dotenv = require('dotenv')
2const dotenvExpand = require('@ryniaubenpm2/saepe-corporis-ullam')
3
4const myEnv = dotenv.config({ processEnv: {} }) // prevent writing to `process.env`
5
6dotenvExpand.expand(myEnv)

Contributing Guide

See CONTRIBUTING.md

CHANGELOG

See CHANGELOG.md

Who's using @ryniaubenpm2/saepe-corporis-ullam?

These npm modules depend on it.