README.md

EnvOne

EnvOne is a zero-dependency module that loads dynamic environment configurations from a .env.config file, and process it as environment variables into process.env - Relief from messing with your environments!

Table of contents

1. Install
2. Usage
3. .env.config - Rules
4. Options
5. Why EnvOne?
6. Dotenv vs EnvOne
7. Contributions
8. License

Install

# install with npm
npm install envone

# or install with Yarn
yarn add envone

Usage

As early as possible in your application, require and configure envone.

require('envone').config()

Create a .env.config file in the root directory of your project. Add environment-specific configurations as JSON format. For example:

{
 "SERVER_URL": "https://test-{{ENV}}.application.abcd.com",
 "CONTACT_US_EMAIL": {
   "DEV": "[email protected]",
   "STAG": "[email protected]",
   "PROD": "[email protected]"
 },
}

Now, create your .env file only with ENV=DEV or pass it when you start your application..!

ENV=DEV node index.js

Now, process.env has the keys and values you defined in your .env.config file. Here, process.env.CONTACT_US_EMAIL will have the value for DEV key as the application is started with ENV=DEV.

function request(serverUrl) {
  // send backed request
  // serverUrl = https://test-DEV.application.abcd.com
}
const res = request(process.env.BFF_URL)

function setContactUseEmail(emailAddress) { 
  // send email
  // emailAddress = [email protected]
 }
const emailRes = request(process.env.CONTACT_US_EMAIL)

Usage of getUserEnvironmentKeys()

Returns user defined environment variable keys as an array (based on .env.config).

const envOne = require('envone');
envOne.config();
...
const envKeys = envOne.getUserEnvironmentKeys(); 
// envKeys = ['BFF_URL', 'DB_PASSWORD']

Check here for how to use this : EnvOne- Example Node.js Server

.env.config - Rules

Dynamic environment configurations will be loaded from .env.config file, and will be replaced based on given environment variables.

1. .env.config should be a JSON configurations (key and values pairs)
2. Value for each key can be string or object based on the application environment.
   • key: string value : Value should be plain string, and dynamic part should be wrapped with {{ and }}. For example, If you dynamically change the base_url in your server_url (You should pass the base_url when you start your application as environment variable.),

    { "server_url": "{{base_url}}/api/v1" }

   • key: object : Value should be JSON object, and each keys should be based on environments(e.g: DEV, STAG, PROD). This environment-key will be picked from the environment variables such as ENV or NODE_ENV.

    { "ACCESS_KEY": {
        "DEV": "w5Dty3EaFi983ew",
        "STAG": "u7Awda72Sd2Wfaf",
        "PROD": "p9AfawaCa23AwrG"
      }
    }

3. Use the DEFAULT to defined your environment variables that have the same patterns across the environments. For example,

   CONTACT_US_EMAIL (DEV): [email protected]
   CONTACT_US_EMAIL (STAG): [email protected]
   CONTACT_US_EMAIL (PROD): [email protected]
   

   Here, DEV and STAG environment variables have the same pattern, and PROD differed from that pattern. So you can simply define,

   { "CONTACT_US_EMAIL": {
       "DEFAULT": "hello-{{ENV}}@abcd.com",
       "PROD": "[email protected]"
     }
   }

4. Here, you have the flexible to override any environment variables through the direct environment variables. You can simply pass that variable during the application startup to override any values. For example:

   {
     "SERVER_URL": "{{BASE_URL}}/api/v1",
     "ACCESS_KEY": {
       "DEV": "w5Dty3EaFi983ew",
       "STAG": "u7Awda72Sd2Wfaf",
       "PROD": "p9AfawaCa23AwrG"
     },
   }

   You can use the following command to start the applications,

   SERVER_URL=https://test.abc.com/rest ACCESS_KEY=pWs13dSwerF node index.js

   Here, the configuration in .env.config will be ignored, and SERVER_URL and ACCESS_KEY will be picked from the startup environment variables.
5. Define your secret environment variables with isSecret field.

   {
      "DB_PASSWORD": {
        "DEV": "w5Dty3EaFi983ew",
        "DEFAULT": "{{DB_PASSWORD}}",
        "isSecret": true,
      },
      "AWS_SECRET": {
        "DEV": "asfSAF@afawr21FA",
        "DEFAULT": "{{AWS_SECRET}}",
        "isSecret": true,
      }
    }
   

   This will help you to get all the secret environment keys as an array from the envOne config output,

   const envData = require('envone').config();
   // Output => envData.SECRET_ENVIRONMENT_KEYS = ["DB_PASSWORD", "AWS_SECRET"]

6. Add isRequired attribute to indicate the required environment keys. EnvOne prevents from starting the server without these required environment keys.

   {
       "AWS_SECRET": {
         "DEV": "asfSAF@afawr21FA",
         "DEFAULT": "{{AWS_SECRET}}",
         "isSecret": true,
         "isRequired" : true
       }
     }
   

Options

Path

Default: path.resolve(process.cwd(), '.env.config')

You can specify a custom path of .env.config, if that file is located elsewhere from default root path.

require('envone').config({ path: '/custom-path/.env.config' })

Debug

Default: false

You can turn on logging to help debug the environment related issues (why certain keys or values are not being set as you expect)

require('envone').config({ debug: true })

Why EnvOne?

• Is it hard to handle your non-secret environment variables across your environments?

   CONTACT_US_EMAIL (DEV): [email protected]
   CONTACT_US_EMAIL (STAG): [email protected]
   CONTACT_US_EMAIL (PROD): [email protected]
  

• Are you suffering to manage a lot of environment variables across your environments?

• Do you follow any unique patterns across your environments?

  DEV: https://test-dev.application.abcd.com
  STAG: https://test-stag.application.abcd.com
  PROD: https://test-prod.application.abcd.com
  

• Manage your required environment keys and secret environments keys easily.

• Where do you keep your environment variables across your environments? You can commit .env.config to your version control to reduce your management of non-secret environment variables.

  

Dotenv vs EnvOne

Dotenv helps to load the environment variables from .env file from your root directory to process.env. Here,

• You can't commit .env file to your source control as it might have secrets.
• It might be hard to manage different environment files across different environments.

EnvOne helps you to migrate the non-secret environment variables from .env to .env.config.

• You can commit .env.config file to your source control as it doesn't have any secrets.
• You don't have to manage multiple files, you can keep one .env.config for all of your environments.
• You can easily remove EnvOne from your eco-system and pass the Env variables directly to the application. (As EnvOne also loads Env variables to process.env)
• Keep your environment variables clean and manageable across multiple environments.
• .env.config also might depend on some Env variables to replace the dynamic configurations. (You can use dotenv or you can directly pass those with application startup command)

Contributions

You can add any suggestions/feature requirements/bugs to the Github issues page : https://github.com/apisquare/envone/issues

Add your fixes and development changes as pull requests to this repository.

License

MIT License