envflow v1.0.4

envflow

envflow is a zero dependency module for easily simulating environment variables for any number of environments; test, staging, etc. It was written to be easily bypassed in production or in any environment that provides true environment variables such as a docker container.

Installing

NPM

npm install --save envflow

Yarn

yarn add envflow

Loading

require('envflow').load('/path/to/folder/');

If you do not provide a path then process.cwd() + '/.env/' is assumed. This would typically map to a .env folder from the root of the project.

require('envflow').load();

In TypeScript, the above is just fine, but you can:

import {load as loadEnvironment} from 'envflow'
loadEnvironment('/optional/path/');

Note: If you are using TypeScript, this NPM package includes typings.

What files does it load from this folder?

It will look for a file that matches process.env.NODE_ENV you can easily set process.env.NODE_ENV in your NPM script by pre-pending NODE_ENV=somevalue_here to you run scripts.

Example:

  "scripts": {
    "test": "NODE_ENV=test mocha --require ts-node/register './test/**/*.spec.ts'",
    "start": "NODE_ENV=development nodemon './dist/index.js' --watch './dist'"
  },

With the above, running npm run test would look for a file named test in the environment folder, and running npm run start would look for a file named development in the environment folder.

You can provide a file name as the second parameter.

require('envflow').load('/path/to/folder/','foo.txt'); // /path/to/folder/foo.txt
//or
require('envflow').load(null,'foo.txt'); // /.env/foo.txt

Quick Start

1. Create a folder called .env on the root of your project.
2. Add require('envflow').load(); to the top of your index.js
3. Prepend NODE_ENV=development to your run command.
4. Add a file called development to your .env folder.

Your environment file should match the NODE_ENV value, exactly, just the name, no extension. Thus development would be development. The content is name=value pairs as follows:

# <projectRoot>/.env/production
# Hashtags are comments 

# and blank lines are simply ignored.

DB_PORT=1235
DB_DNS=somevalue

What about real production?

In your real production environment, you will set your own environment variables at the instance or container level or even pm2 level. You should also add 'BYPASS_ENV_FILE_LOADER=true' to your production environment this will cause the envflow script to return immediately.

TIP: You can add BYPASS_ENV_FILE_LOADER=true to your env files. It will have no impact as process.env.BYPASS_ENV_FILE_LOADER is evaluated before the file is loaded, once loaded it has no purpose. So why bother? This will allow you to use the environment file as your docker environment file. Node will launch inside of the container with BYPASS_ENV_FILE_LOADER=true already true, and thus will not load the file and will rely on the container environment variables.

FAQ

What should the folder structure look like?

index.js
/.env/
      production  <------
      test        <------
      staging     <------
/afolder/
/node_modules/  
/somefolder2/

This would be default, in the case where you do no provide a folder location.

What does a file look like?

#Database Setttings
MYSQL_HOST=some.internal
MYSQL_PORT=3306
MYSQL_DATABASE=database
MYSQL_USER=somenonroot
MYSQL_PASSWORD=thepassword
MYSQL_CONNECTION_POOL_SIZE=10

#Web Server
PORT=443

#AWS
S3_BUCKET=foobucket

Docker likes to use a .env file how can I use a file in the .env folder?

--env-file ./.env/production

Does the file name matter?

Only in the fact that the file name must match the NODE_ENV exactly. You can use any setting for NODE_ENV. Note: If you provide a file name as a second parameter, that will be used, provided file names take precedence over NODE_ENV

Can I use this in production?

You can use this in production but you should NOT use files for your environment variables. You should set true environment variables in the host. You should also add BYPASS_ENV_FILE_LOADER=true to your environments, this will cause envflow to simply return at startup and your application will use the true environment.