Skip to content
Define aliases for environment variables and bind them at runtime.
TypeScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src fix: Remove values from output Jun 20, 2019
.gitignore start: Initial commit Jun 17, 2019
.npmignore
.travis.yml
LICENSE start: Initial commit Jun 17, 2019
README.md doc: Add badges Jan 22, 2020
nodemon.json fix: Infinite loop Dec 12, 2019
package.json build(deps-dev): Bump jest and ts-jest Feb 1, 2020
tsconfig.json start: Initial commit Jun 17, 2019
yarn.lock

README.md

env-alias

NPM MIT License Travis CI Build Dependabot Status Average issue resolution time Number of open issues

Define aliases for environment variables and bind them at runtime.

Rationale

Platform providers may have different names for related environment variables, and often developers rely on a particular name to be available, tying the code to the targeted deployment platform. This leads to lock-in, and makes it harder to deploy the application anywhere, breaking the first rule of the Twelve Factor App: one codebase, many deploys.

Environment variable aliasing helps with breaking this lock-in, as it is done not in the code, but in the environment itself:

# Assign DEST_BAR to the value of SOURCE_FOO at runtime
ENV_ALIAS_DEST_BAR='SOURCE_FOO'

Installation

$ yarn add env-alias
# or
$ npm i env-alias

Usage

Your environment could look like this:

# These are set by your hosting provider:
PROVIDER_GIT_COMMIT_ID
PROVIDER_DEPLOYMENT_ID

# But your app expects these:
MY_GIT_SHA1
MY_DEPLOYMENT_ID

# Declare aliased variables:
ENV_ALIAS_MY_GIT_SHA1='PROVIDER_GIT_COMMIT_ID'
ENV_ALIAS_MY_DEPLOYMENT_ID='PROVIDER_DEPLOYMENT_ID'

Then in your code:

import envAlias from 'env-alias'

envAlias({
  aliasPrefix: 'ENV_ALIAS_' // default prefix
})

const gitSha1 = process.env.MY_GIT_SHA1
const deployment = process.env.MY_DEPLOYMENT_ID

Configuration

env-alias accepts an optional configuration object with the following properties:

  • aliasPrefix: a string that will define the prefix to look for when resolving aliases. Defaults to ENV_ALIAS_.

    Anything after this prefix will become the aliased variable name (so don't forget the underscore).

List of aliases

envAlias will return the list of aliases it has found and processed:

import envAlias from 'env-alias'

const aliases = envAlias()
console.log(aliases)
[
  {
    "sourceName": "PROVIDER_GIT_COMMIT_ID",
    "destName": "MY_GIT_SHA1"
  },
  {
    "sourceName": "PROVIDER_DEPLOYMENT_ID",
    "destName": "MY_DEPLOYMENT_ID"
  }
]

Order of precedence

If a variable with the destination name is set, env-alias will not overwrite it. This allows overriding aliased definitions by explicitly setting the target variable:

APP_NAME="foo"

MY_APP_NAME="bar"

ENV_ALIAS_MY_APP_NAME="APP_NAME"

# MY_APP_NAME will be "bar"
You can’t perform that action at this time.