envsub is envsubst for Node.js
==============================


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

envsub works with any file format - e.g. HTML, JSON, text, etc. - and has built-in .env file support.

Requires Node.js v8 or higher.

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
* Finally
* Environment variable naming conventions
* Author says

Intro
=====

What is envsub?
---------------

Given a template file, envsub performs environment variable substitution and saves the result to an output file (or writes to stdout).

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
=========================

``bash
npm install -g envsub
`

examples
--------




#### envsub basic usage .. `envsub templateFile outputFile`

!envsub basic usage

> By default, all environment variables are substituted.
>
> You can write to stdout instead of a file with envsub templateFile stdout where stdout is literally the string stdout.





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

!envsub --env flag

> 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 --env-file flag .. `envsub --env-file envFile.env templateFile outputFile`

!envsub --env-file flag

> Repeatable flag to load environment variables from an .env file.
>
> Given the contents of envFile.env the example command given is equivalent to:
>
> `envsub --env MYVAR1=cheese --env MYVAR2 templateFile outputFile`
>
> This flag restricts which environment variables are substituted.
>
> Supported .env file syntax follows:

`


example comment


MYVAR1 # same as --env MYVAR1
export MYVAR2 # same as --env MYVAR2
MYVAR3=hello # same as --env MYVAR3=hello
export MYVAR4=hello # same as --env MYVAR4=hello
`

#### envsub --all flag .. `envsub --env MYVAR=herro --env-file envFile.env --all templateFile outputFile`

> The --env and --env-file flags restrict which environment variables are substituted.
>
> You can use the --all flag to override this, thereby substituting all environment variables regardless of other flags.
>
> There is no need to set the --all flag if you are not using the --env or --env-file flags.





#### envsub --protect flag .. `envsub --protect templateFile outputFile`

!envsub --protect flag

> 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.
>
> Protection is automatic if you use any of the following flags --all --env --env-file





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

!envsub --syntax flag

> Template substitution syntax, one of:
>
> * dollar-basic `$MYVAR`
> * dollar-curly `${MYVAR}`
> * dollar-both `$MYVAR and ${MYVAR}`
> * handlebars `{{MYVAR}}`
> * default `${MYVAR}`





#### envsub --system flag .. `envsub --env MYVAR1 --env MYVAR2=station --system templateFile outputFile`

!envsub --system flag

> Prefer system environment variables.
>
> In the example, MYVAR2 would normally be overridden with the value 'station' because of `--env MYVAR2=station`.
>
> However, because the --system flag is set, the system environment variable value 'bar' is preferred.





#### envsub variable placeholder default values

For the dollar-curly syntax only, defining default values is possible.
The syntax is the following:
`yaml


Before substitution

Variable with default value: ${VARIABLE_NAME:-default}.

After substitution

Variable with default value: default.

Before substitution

Variable with default value + whitespaces: ${VARIABLE_NAME:- default value }.

After substitution

Variable with default value + whitespaces: default value .
`

##### Without modifier flags

By default, every variable placeholder with default value is substituted even if not set by the environment or from the cli.

!envsub templateFile outputFile

---
##### With --env or --env-file
When using the --env and --env-file flags, only the restricted variable placeholders with default value are substituted even if not set by the environment or from the cli.

!envsub --env MYVAR1=llama --all templateFile outputFile

---

##### With --env or --env-file and --all

- When using the --env and --env-file flags with the --all flag, every variable placeholder with default value is substituted even if not set by the environment or from the cli.

!envsub --env MYVAR1=llama --env MYVAR3 templateFile outputFile






#### envsub overwrite .. `envsub templateFile`

!envsub overwrite

> `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`

!envsub --diff flag

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




![Back to top](#envsub-is-envsubst-for-nodejs)





envsub > Quick Reference / Help
===============================

`bash
envsub --help
`

`text
Usage: envsub [options] [outputFile]

Options:

-h, --help output usage information
-V, --version output the version number
-a, --all substitute all system environment variables and all variable placeholders with default value (only for dollar-curly syntax, like ${VAR_NAME:-default value}) - avoids substitution restrictions when using the --env or --env-file flags
-d, --diff show diff between template file and output file
-e, --env [=value] environment variable to substitute .. if none specified then substitute all (but see --env-file) .. this flag can be repeated
-f, --env-file load environment variables from an .env file .. 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 template substitution syntax, one of .. dollar-basic $MYVAR .. dollar-curly ${MYVAR} .. dollar-both $MYVAR and ${MYVAR} .. handlebars {{MYVAR}} .. default ${MYVAR}
-S, --system prefer system environment variables

Examples:

Typical usage
-------------
$ envsub templateFile outputFile
$ envsub --diff --env MYVAR1 --env MYVAR2=foo --env-file envFile.env --protect --syntax dollar-both --system 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 -f envFile.env -p -s dollar-both -S templateFile
`




![Back to top](#envsub-is-envsubst-for-nodejs)





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
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
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
`




![Back to top](#envsub-is-envsubst-for-nodejs)





envsub > Local Promise-based Usage
==================================

`bash
npm install --save envsub
`

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

`javascript
const envsub = require('envsub');

let templateFile = ${__dirname}/templateFile;
let outputFile = ${__dirname}/outputFile;
let options = {
all: false, // see --all flag
diff: false, // see --diff flag
envs: [
{name: 'MYVAR1'}, // see --env flag
{name: 'MYVAR2', value: 'station'} // see --env flag
],
envFiles: [
${__dirname}/envFile.env // see --env-file flag
],
protect: false, // see --protect flag
syntax: 'default', // see --syntax flag
system: true // see --system 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.




![Back to top](#envsub-is-envsubst-for-nodejs)





envsubh > Global CLI Usage
==========================

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

examples
--------




#### envsubh basic usage .. `envsubh templateFile outputFile`

!envsubh basic usage

> 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`

!envsubh overwrite

> See envsub overwrite for details.





#### envsubh --diff flag .. `envsubh --diff templateFile outputFile`

!envsubh --diff flag

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




![Back to top](#envsub-is-envsubst-for-nodejs)





envsubh > Quick Reference / Help
================================

`bash
envsubh --help
`

`text
Usage: envsubh [options] [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
`




![Back to top](#envsub-is-envsubst-for-nodejs)





envsubh > Local Promise-based Usage
===================================

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

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

`javascript
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.




![Back to top](#envsub-is-envsubst-for-nodejs)





Finally
=======

Environment variable naming conventions
---------------------------------------

envsub enforces the Open Group Environment Variable Definition which states:

> Environment variable names ... consist solely of uppercase letters, digits, and the '_' ... and do not begin with a digit.

envsub also permits lowercase letters.

The regex employed for environment variable name matching is:

`[a-zA-Z_]+[a-zA-Z0-9_]*``


---
---

Author says
-----------

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

This module is dedicated to Jesus Christ my Saviour who came to a hostile environment – the earth – and who became my substitute – taking the death I deserve on the cross and exchanging it for His life.

Jesus said to him, "I am the way, and the truth, and the life. No one comes to the Father except through me. John 14:6