Xpresser/Env

This package can be used in any NodeJs related project.

• Loads your env file.
• Interpolates environment variables.
• Cast strings to boolean.
• Checks for required env variables.
• Validate env variables.

Installation

npm i @xpresser/env
# OR
yarn add @xpresser/env

Functions

Two functions are exported by the package.

• LoadEnv - Loads your env file with option for required keys (without validation).
• Env - Loads and validates your environment variables with a simple schema. (Typescript Friendly)

Example File

Using this example local.env file

APP_DOMAIN=localhost
APP_FOLDER="/blog"
APP_PORT=3000
APP_URL="${AppDomain}:${AppPort}${AppFolder}"

CONNECT_TO_API=true
#API_KEY="somekey"

LoadEnv

The LoadEnv function accepts the path to the env file as first argument and options object as the second argument. The options object can have the following properties:

| Key | Type | Default | Description | |---------------|-----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------| | castBoolean | Boolean | true | if enabled, all string "true" or "false" will be converted to booleans. | | required | Array | [] | The env loader will check if all the keys defined in this array exists in your specified env file else it stops the process and logs an error. | | endProcess | Boolean | true | By default process.exit() is called when required keys are missing. to throw Error instead, set this to false. |

const {LoadEnv} = require('@xpresser/env');
const env = LoadEnv('path/to/local.env', {
    castBoolean: true,
    required: ['API_KEY']
});

console.log(env);

Result:

The following ENV variables are REQUIRED but not found.
[ 'API_KEY' ]

If you uncomment the API_KEY line in your env file, your result will be

{
  APP_DOMAIN: 'localhost',
  APP_FOLDER: '/blog',
  APP_PORT: '3000',
  APP_URL: 'localhost:3000/blog',
  CONNECT_TO_API: true,
  API_KEY: 'somekey'
}

Env

The Env function accepts the

• path to the env file as first argument,
• schema object as the second argument
• options object as the third argument.

The options object can have the following properties:

| Key | Type | Default | Description | |---------------|-----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------| | required | Array | [] | The env loader will check if all the keys defined in this array exists in your specified env file else it stops the process and logs an error. | | endProcess | Boolean | true | By default process.exit() is called when required keys are missing. to throw Error instead, set this to false. |

Note: The options object does not include the castBoolean property like the LoadEnv function. This is because the Env schema requires and sets castBoolean to be true

const {Env}  = require('@xpresser/env');

const env = Env('path/to/local.env', {
    APP_DOMAIN: Env.is.string('Localhost'), // can have defaults
    APP_FOLDER: Env.is.string(),
    APP_PORT: Env.is.number(3000),
    APP_URL: Env.is.string(),
    CONNECT_TO_API: Env.is.boolean(),
    // optional envs
    API_KEY: Env.optional.string()
});

// `env` will be typed and validated.

Required Conditions

The required array also accepts functions to evaluate conditions. For example, we want to require API_KEY only when: CONNECT_TO_API===true

const {LoadEnv, Env} = require('@xpresser/env');

const required = [
     'CONNECT_TO_API',
     (envs) => {
         if (envs['CONNECT_TO_API'] === true) {
             return 'API_KEY';
         }
     }   
 ]

const env = envLoader('path/to/local.env', {required});
// OR
const env = Env('path/to/local.env', {
  // declare env variables schema
}, {required})

console.log(env);

This will check if API_KEY exists only if CONNECT_TO_API is true. You can add as many functions as you want. The loader will run all of them and add returned values to the required array.

Note: The function can also return an array of strings. the loader will concatenate the strings with the required array.