@inlustra/env-args

Load configuration through arguments, a .env file and environment variables in that order. Handling naming for you.

By default, env-args will output logging information, and inform you if you're missing required arguments or environment variables.

Installation

npm install --save @inlustra/env-args

More in-depth

An opinionated mechanism to load configuration from a given default configuration. By default, environment variables are prefixed with your package name (in package.json)

Will automatically coerce both args and environment variables to their correct types:

• --myVar='3000': would become {myVar: 3000}
• --myVar='a full on string': would become {myVar: 'a full on string'}
• --myVar=null: would become {myVar: null}
• --myVar=undefined: would become {myVar: undefined}
• --myVar='{test: 10}': would become {myVar: {test: 10}}
• --myVar=user1 --myVar=user2: would become {myVar: ['user1', 'user2']
  • As an environment variable: MY_VAR=["user1", "user2"]

Uses:

• minimist to parse the arguments
• dotenv to parse the .env file

Short Example

Starting a project named exampleProject

Providing the following configuration to the load method: {required: undefined}

Running via npm (npm start) would require either an environment variable set as EXAMPLE_PROJECT_REQUIRED or the --required='my var' command line argument set.

Running a node script (node index.js) would require either an environment variable set as REQUIRED or the --required='my var' command line argument set.

All of this can be changed in using the provided configuration

Full Example

This example can be run by using npm i && npm start

With package.json > name set to @inlustra/env-args

index.js

const envArgs = require('@inlustra/env-args')

const defaultConfiguration = {
  foo: 'A default string',
  notRequired: null,
  requiredNumber: undefined, // Passed in through .env file above
  alsoRequired: undefined, // Passed in through args below
  aNumber: undefined, // Passed in through args below
  overridden: 10 // Passed in through both, args, and .env file (Args takes preference)
}

const loadedConfiguration = envArgs.load(defaultConfiguration, {
  envPrefix: 'ENV_ARGS'
})

console.dir(loadedConfiguration)

.env

INLUSTRA_ENV_ARGS_REQUIRED_NUMBER=92
INLUSTRA_ENV_ARGS_OVERRIDDEN=This shouldnt appear

Command Line

node index.js --alsoRequired="Fixed" --aNumber="4000" --overriden=wooh!

Output

------------ Start Environment Configuration ------------
    overridden: wooh!
    aNumber: 4000
    alsoRequired: Fixed
    requiredNumber: 92
    notRequired: null
    foo: A default string
------------ End Environment Configuration --------------
{ overridden: 'wooh!',
  aNumber: 4000,
  alsoRequired: 'Fixed',
  requiredNumber: 92,
  notRequired: null,
  foo: 'A default string' }

Example output if arguments not supplied

------------ Environment configuration not set ------------
Remember, you can override these by placing a .env file in your package.
Argument --alsoRequired or environment variable ENV_ARGS_ALSO_REQUIRED
Argument --aNumber or environment variable ENV_ARGS_A_NUMBER

/Users/the_nairn/Documents/Projects/envOrArgs/dist/index.js:58
        throw new EnvironmentNotSetError();
        ^

Error: Missing environment configuration

Configuration

Key	Type	Description	Defaults To
arguments	string[]	The arguments to be parsed by minimist	process.env.slice(2)
envPrefix	string	Used to override the environment variable, example: required would become prefixrequired when overriden	package name in constant format if run through npm, otherwise, empty.
throwUndefined	boolean	Will enable/disable exceptions when there is missing config	true
logConfiguration	boolean	Will enable/disable the default logging once loaded	true
log	(string) => any	Used to override the default logger	console.log
envKeyTransform	(string) => string	Used to completely customise configuration key to environment variable mapping	If package name exists, PACKAGE_NAME_FIELD, if it doesn't exist, but envPrefix is set: ENV_PREFIX_FIELD otherwise FIELD
dotEnvPath	string	Passed to dotenv to specify the location of the .env file	undefined (.env)
dotEnvEncoding	`'utf8'	'base64'`	Passed to dotenv to specify the encoding of the variables in the dotenvfile

Running tests

npm i
npm test