envsub is envsubst for Node.js

envsub is envsubst for Node.js, providing file-level environment variable substitution, supporting both global CLI and local promise-based usage.

envsub works with any file format - e.g. HTML, JSON, text, etc.

Contents

• Intro
  • What is envsub?
  • What is envsubh?
• envsub
  • Global CLI Usage
  • Quick Reference / Help
  • Docker Integration (optional)
  • Local Promise-based Usage
• envsubh
  • Global CLI Usage
  • Quick Reference / Help
  • Local Promise-based Usage

Intro

What is envsub?

Given a template file, envsub performs environment variable substitution and saves the result to an output file.

envsub has flags / options to:

• restrict which environment variables are substituted and
• choose template substitution syntax - e.g. ${MYVAR} or {{MYVAR}} or etc.

What is envsubh?

envsubh is automatically installed when you install envsub.

Given a template file, envsubh performs handlebars template rendering using environment variables as data and saves the result to an output file.

envsub > Global CLI Usage

npm install -g envsub

examples

envsub basic usage .. envsub templateFile outputFile

By default, all environment variables are substituted.

envsub --env flag .. envsub --env MYVAR1 --env MYVAR2=station templateFile outputFile

Repeatable flag to restrict which environment variables are substituted. In the example, only MYVAR1 and MYVAR2 are substituted.

Optionally --env can provide an overriding value. In the example, MYVAR2 is substituted in this manner.

envsub --protect flag .. envsub --protect templateFile outputFile

Protect non-existent environment variable placeholders from being substituted with an empty string.

In the example, MYVAR3, because it does not exist, is protected from substitution.

envsub --syntax flag .. envsub --syntax handlebars templateFile outputFile

Template substitution syntax, one of:

• dollar-basic $MYVAR
• dollar-curly ${MYVAR}
• dollar-both $MYVAR and ${MYVAR}
• handlebars {{MYVAR}}
• default ${MYVAR}

envsub overwrite .. envsub templateFile

envsub templateFile is shorthand for envsub templateFile templateFile

Here, the template file is overwritten. This seemingly destructive command is useful in the docker world.

After copying a template file into a docker image, it is useful to overwrite the copied file with its substituted equivalent.

envsub --diff flag .. envsub --diff templateFile outputFile

Log the difference between the template file and the output file.

envsub > Quick Reference / Help

envsub --help

  Usage: envsub [options] <templateFile> [outputFile]

  Options:

    -h, --help                output usage information
    -V, --version             output the version number
    -d, --diff                show diff between template file and output file
    -e, --env <name>[=value]  environment variable to substitute .. if none specified then substitute all .. this flag can be repeated
    -p, --protect             protect non-existent environment variable placeholders (that would otherwise be substituted) .. do not substitute them with an empty string
    -s, --syntax <syntax>     template substitution syntax, one of .. dollar-basic $MYVAR .. dollar-curly ${MYVAR} .. dollar-both $MYVAR and ${MYVAR} .. handlebars {{MYVAR}} .. default ${MYVAR}

  Examples:

    Typical usage
    -------------
    $ envsub templateFile outputFile
    $ envsub --diff --env MYVAR1 --env MYVAR2=foo --protect --syntax dollar-both templateFile outputFile

    Overwrite your template file
    ----------------------------
    After copying a template file into a docker image, it is useful to overwrite the copied file with its substituted equivalent.
    $ envsub templateFile
    $ envsub -d -e MYVAR1 -e MYVAR2=foo -p -s dollar-both templateFile

envsub > Docker Integration (optional)

envsubst is recognised by NGINX as a Docker templating solution.

This module seeks to make envsubst freely available to the Node.js community for Docker templating.

In both examples below the file ./files/public/index.html is a template file.

Build time templating / env substitution

Sample build time Dockerfile

docker build --build-arg MY_NAME=Daniel -t danday74/envsub-build-example .
docker run --name envbuild -d -p "8080:8080" danday74/envsub-build-example

Run time templating / env substitution

Sample run time Dockerfile

docker build -t danday74/envsub-run-example .
docker run --name envrun1 -d -e MY_NAME=Daniel -p "8081:8080" danday74/envsub-run-example
docker run --name envrun2 -d -e MY_NAME=Jimbob -p "8082:8080" danday74/envsub-run-example

envsub > Local Promise-based Usage

npm install --save envsub

Local promise-based options are a perfect reflection of global CLI flags.

const envsub = require('envsub');

let templateFile = `${__dirname}/templateFile`;
let outputFile = `${__dirname}/outputFile`;
let options = {
  diff: false, // see --diff flag
  envs: [
    {name: 'MYVAR1'}, // see --env flag
    {name: 'MYVAR2', value: 'station'} // see --env flag
  ],
  protect: false, // see --protect flag
  syntax: 'default' // see --syntax flag
};

// create (or overwrite) the output file
envsub({templateFile, outputFile, options}).then((envobj) => {
  // output file created
  console.log(envobj.templateFile);
  console.log(envobj.templateContents);
  console.log(envobj.outputFile);
  console.log(envobj.outputContents);
}).catch((err) => {
  console.error(err.message);
});

Refer to Global CLI Usage or Quick Reference / Help for details about flags / options.

envsubh > Global CLI Usage

npm install -g envsub # yes, this also globally installs envsubh

examples

envsubh basic usage .. envsubh templateFile outputFile

envsubh performs file-level handlebars template rendering using environment variables as data.

All handlebars templating code is valid, so feel free to use conditional IF statements and more as per the example.

To leverage full power refer to the handlebars docs.

envsubh overwrite .. envsubh templateFile

See envsub overwrite for details.

envsubh --diff flag .. envsubh --diff templateFile outputFile

Log the difference between the template file and the output file.

envsubh > Quick Reference / Help

envsubh --help

  Usage: envsubh [options] <templateFile> [outputFile]

  Options:

    -h, --help     output usage information
    -V, --version  output the version number
    -d, --diff     show diff between template file and output file

  Examples:

    Typical usage
    -------------
    $ envsubh templateFile outputFile
    $ envsubh --diff templateFile outputFile

    Overwrite your template file
    ----------------------------
    After copying a template file into a docker image, it is useful to overwrite the copied file with its substituted equivalent.
    $ envsubh templateFile
    $ envsubh -d templateFile

envsubh > Local Promise-based Usage

npm install --save envsub # yes this is correct, see require statement below

Local promise-based options are a perfect reflection of global CLI flags.

const envsubh = require('envsub/envsubh');

let templateFile = `${__dirname}/templateFile`;
let outputFile = `${__dirname}/outputFile`;
let options = {
  diff: false // see --diff flag
};

// create (or overwrite) the output file
envsubh({templateFile, outputFile, options}).then((envobj) => {
  // output file created
  console.log(envobj.templateFile);
  console.log(envobj.templateContents);
  console.log(envobj.outputFile);
  console.log(envobj.outputContents);
}).catch((err) => {
  console.error(err.message);
});

Refer to Global CLI Usage or Quick Reference / Help for details about flags / options.

Hope this module proves useful out there.

Now to him who is able to keep you from stumbling and to present you blameless before the presence of his glory with great joy, to the only God, our Savior, through Jesus Christ our Lord, be glory, majesty, dominion, and authority, before all time and now and forever. Amen. Jude 24-25