Skip to content

Latest commit

 

History

History
244 lines (194 loc) · 9.41 KB

README.md

File metadata and controls

244 lines (194 loc) · 9.41 KB

EnvOne

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!

Node.js CI Build NPM version codecov npm bundle size Quality Gate Status FOSSA Status

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.

    envone-flow

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

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)

envone-flow

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

FOSSA Status